404 页面
创建 404 模板,为未找到的地址渲染错误页面:最小可运行示例、本地验证方法、多语言写法与托管平台配置差异。
开始之前,你需要
读完之后你能
- 在
layouts/根目录创建 404 模板,并确认构建产物里真的出现了public/404.html; - 在本地用一个不存在的地址检查 404 页面,而不是等上线才发现;
- 为多语言站点准备按语言键区分的 404 模板;
- 知道「文件生成了、线上却看不到」通常是服务器的配置问题,而不是 Hugo 的问题。
接着读:robots.txt · 内容类型 · 托管与部署
这一页解决什么问题
访客点到一个已经不存在的地址时,站点需要给出一张「页面不存在」的页面,并把他引回有用的内容。这张页面由 layouts/404.html 渲染,构建后输出为站点根目录下的 404.html。
这里有一处分工必须先讲清楚,它决定了「为什么我生成了 404 页面,线上却是服务器默认页」:
- Hugo 负责生成:把模板渲染成
public/404.html; - 服务器负责使用:访客访问不存在的地址时,由生产服务器决定是否把浏览器导向这个文件。
所以本页分两半:写模板(本地就能验证完),和配置服务器(只能在线上验证,且各托管平台的做法不同)。
创建 404 模板
在站点根目录输出一个 404 错误页面,需要在 layouts 目录的根下创建 404 模板。注意它与普通页面模板的位置不同:单页模板、列表模板都放在子目录中(或者按 Hugo 的模板查找规则层层向上查找),而 404 模板只认 layouts 根目录,放在别处不会被采用。
{{ define "main" }}
<h1>404 Not Found</h1>
<p>您请求的页面不存在。</p>
<p>
<a href="{{ .Site.Home.RelPermalink }}">
返回首页
</a>
</p>
{{ end }}模板内部可以调用站点和页面对象,例如上面用 .Site.Home.RelPermalink 取得首页地址,让误入的访客有一条明确的退路。构建之后,Hugo 会在 publishDir(通常是 public)的根目录生成 404.html,与普通页面不同,它不受语言前缀或目录结构影响,始终位于站点根目录。
写法上,404 模板有两种选择:像上面那样用 define 定义主内容块,由站点的基础模板(base template)补上页头、页脚等外壳;或者把整份 HTML 都写在这个文件里。前者能复用主题的导航与样式,后者更简单直接。需要注意的是,Hugo 不会替你生成一份带内容的 404 页面:没有提供模板时,服务器即使把访客导向 404 地址,看到的也是一片空白。
最小可运行示例
上面那份模板依赖站点存在 baseof.html 并提供 main 块。如果你的站点还没有基础模板,用下面这份自包含版本最稳妥:把它原样保存成 layouts/404.html,不依赖任何其他文件。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>404 Not Found</title>
</head>
<body>
<h1>404 Not Found</h1>
<p>您请求的页面不存在。</p>
<p><a href="{{ .Site.Home.RelPermalink }}">返回首页</a></p>
</body>
</html>结果长什么样
构建之后,产物固定落在 public/404.html(用 hugo 构建后可以直接用编辑器打开):
public/
├── 404.html <-- 本页模板的输出
├── index.html
├── robots.txt
└── sitemap.xml渲染出来的 HTML 大致是(.Site.Home.RelPermalink 会被替换成首页地址):
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>404 Not Found</title>
</head>
<body>
<h1>404 Not Found</h1>
<p>您请求的页面不存在。</p>
<p><a href="/">返回首页</a></p>
</body>
</html>注意:404.html 的内部链接(如上面的 /)最好写根相对路径。它有可能是从任意深度的不存在地址被打开,用页面相对的 ../ 会指向错误的位置。
本地验证 404 页面
本地不需要任何服务器配置就能验证模板本身:
hugo server然后访问一个确认不存在的地址,例如 http://localhost:1313/no-such-page/。你应当看到:
- 浏览器里出现你写的 404 页面(标题、提示语、返回首页的链接都齐全);
- 点击「返回首页」能回到站点首页;
- 终端里没有
ERROR。
hugo server 会在找不到页面时返回这份 404 输出,这正好用来检查链接与多语言提示是否正确;确认无误再部署到托管平台,就不必等到线上才发现 404 页面是一段空白或被服务器默认页替换掉。
多语言处理
多语言站点的 404 页面通过文件名中的语言键区分,例如德语、英语、法语各一份:
layouts/
├── 404.de.html
├── 404.en.html
└── 404.fr.htmlHugo 会为每种语言使用与语言键匹配的那份模板;语言键与站点配置中的语言代码对应。这样做的意义在于,404 页面上的提示语、返回首页的链接文字都可以按语言分别撰写,而不是让所有语言的访客共用一份英文提示。需要为所有语言提供同名的文件,否则某种语言的 404 页面会回退到不带语言键的通用模板(如果存在的话)。翻译内容也可以交给翻译表处理,把提示文字放在 i18n 目录下,模板里通过 T 函数取值,这样 404 模板本身只需维护一份。
多语言的验证标准
给语言键版本做检查时,除了「页面能打开」,还要确认取到的是对应语言的内容:
- 用不同语言的 URL 前缀各访问一个不存在的地址(例如
/de/nicht-vorhanden/与/no-such-page/); - 两者应当显示不同语言的提示语;如果都显示同一种语言,检查
404.<语言键>.html的文件名与站点配置里的语言代码是否一致。
服务器端配置
Hugo 只负责把 404.html 生成到站点根目录,是否在页面未找到时把浏览器导向它,由生产服务器决定。静态托管服务的支持程度和配置方式各不相同:有的服务会自动使用根目录下的 404.html,有的需要在控制台或配置文件中显式指定错误文档;个别服务的重定向是自动进行且不可配置的。部署之前请查阅所用托管平台的文档:
| 托管平台 | 能力与配置 |
|---|---|
| Amazon CloudFront | 见官方说明 |
| Amazon S3 | 见官方说明 |
| Apache | 见官方说明 |
| Azure Static Web Apps | 见官方说明 |
| Azure Storage | 见官方说明 |
| Caddy | 见官方说明 |
| Codeberg Pages | 见官方说明 |
| Cloudflare Pages | 见官方说明 |
| DigitalOcean App Platform | 见官方说明 |
| Firebase | 见官方说明 |
| GitHub Pages | 自动重定向到 404.html,不可配置 |
| GitLab Pages | 见官方说明 |
| NGINX | 见官方说明 |
| Netlify | 见官方说明 |
国内常见的部署方式里,Nginx(含宝塔面板等)需要在 server 块里显式写 error_page 404 /404.html;;对象存储(阿里云 OSS、腾讯云 COS)通常要在控制台把「错误文档」设为 404.html 并让它返回 404 状态码,而不要设成「默认首页」,否则所有不存在的地址都会返回 200,搜索引擎会把这些垃圾地址当成正常页面收录。
常见坑
| 类别 | 现象 | 原因与处理 |
|---|---|---|
| 命令找不到 | hugo: command not found / 「不是内部或外部命令」 |
Hugo 没装好或没进 PATH,与 404 模板无关 → 安装 Hugo |
| 没报错但结果不对 | 构建成功,但 public/404.html 不存在 |
模板没放在 layouts/ 根目录(放进了 _default/、子目录或主题目录但主题没启用)→ 对照模板查找顺序确认位置 |
| 没报错但结果不对 | 本地能看到 404 页面,线上看不到 | Hugo 已经生成文件,但服务器没配置错误文档 → 见上文各平台表格 |
| 没报错但结果不对 | 打开 404 页时样式丢失 | 模板里用了相对路径(../css/…)→ 改成根相对路径或配合 absURL |
| 报错看不懂 | 构建时出现 found no layout file for … 一类警告 |
名字或位置不对,Hugo 只给警告、该页面为空 → 把文件名改成 layouts/404.html 后重新构建 |
| 报错看不懂 | 加了 define 却报找不到 main 块 |
站点没有 baseof.html 或基础模板里没有对应的 block → 改用本页「最小可运行示例」的自包含写法 |
更多排查入口见故障排查。