模板

404 页面

创建 404 模板,为未找到的地址渲染错误页面:最小可运行示例、本地验证方法、多语言写法与托管平台配置差异。

难度
入门
预计用时
10–15 分钟

开始之前,你需要

  • 有一个能用 hugo server 跑起来的站点(见快速开始)。
  • 知道 layouts/ 在哪,以及基础模板(baseof.html)里 block 与 define 的基本分工(见内容类型)。

读完之后你能

  • 在 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 根目录,放在别处不会被采用。

layouts/404.htmlgo-html-template
{{ 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,不依赖任何其他文件。

layouts/404.htmlgo-html-template
<!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 会被替换成首页地址):

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="/">返回首页</a></p>
</body>
</html>

注意:404.html 的内部链接(如上面的 /)最好写根相对路径。它有可能是从任意深度的不存在地址被打开,用页面相对的 ../ 会指向错误的位置。

本地验证 404 页面

本地不需要任何服务器配置就能验证模板本身:

bash
hugo server

然后访问一个确认不存在的地址,例如 http://localhost:1313/no-such-page/。你应当看到:

  • 浏览器里出现你写的 404 页面(标题、提示语、返回首页的链接都齐全);
  • 点击「返回首页」能回到站点首页;
  • 终端里没有 ERROR。

hugo server 会在找不到页面时返回这份 404 输出,这正好用来检查链接与多语言提示是否正确;确认无误再部署到托管平台,就不必等到线上才发现 404 页面是一段空白或被服务器默认页替换掉。

多语言处理

多语言站点的 404 页面通过文件名中的语言键区分,例如德语、英语、法语各一份:

tree
layouts/
├── 404.de.html
├── 404.en.html
└── 404.fr.html

Hugo 会为每种语言使用与语言键匹配的那份模板;语言键与站点配置中的语言代码对应。这样做的意义在于,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 → 改用本页「最小可运行示例」的自包含写法

更多排查入口见故障排查。