404 页面

自定义 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 地址，看到的也是一片空白。

多语言处理

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

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

Hugo 会为每种语言使用与语言键匹配的那份模板；语言键与站点配置中的语言代码对应。这样做的意义在于，404 页面上的提示语、返回首页的链接文字都可以按语言分别撰写，而不是让所有语言的访客共用一份英文提示。需要为所有语言提供同名的文件，否则某种语言的 404 页面会回退到不带语言键的通用模板（如果存在的话）。翻译内容也可以交给翻译表处理，把提示文字放在 i18n 目录下，模板里通过 T 函数取值，这样 404 模板本身只需维护一份。

服务器端配置

Hugo 只负责把 404.html 生成到站点根目录，是否在页面未找到时把浏览器导向它，由生产服务器决定。静态托管服务的支持程度和配置方式各不相同：有的服务会自动使用根目录下的 404.html，有的需要在控制台或配置文件中显式指定错误文档；个别服务（例如 GitHub Pages）的重定向是自动进行且不可配置的。部署之前请查阅所用托管平台的文档。

本地验证

生成结果是否正确，在本地就能验证：运行 hugo server 后随便访问一个不存在的地址，浏览器里出现的就是这份 404 页面。用它检查返回首页的链接是否可用、多语言下的提示语是否取到了对应语言，再部署到托管平台；这样就不必等到线上才发现 404 页面其实是一段空白或被服务器默认页面替换掉了。