# 404 页面
> 创建 404 模板，为未找到的地址渲染错误页面。
- 官方英文原文：https://gohugo.io/templates/404/
- 本页规范地址：https://hugozh.cn/templates/404/
- 最近更新：2026-10-02
- 最后提交：912b1d3 chore(site): 添加 static/CNAME（hugozh.cn），供 GitHub Pages 等平台绑定自定义域名
- 站点：Hugo 中文文档（https://hugozh.cn/）· 社区维护的非官方中文翻译，如有出入以官方英文原文为准

---
## 自定义 404 页面

在站点根目录输出一个 404 错误页面，需要在 `layouts` 目录的**根**下创建 404 模板。注意它与普通页面模板的位置不同：单页模板、列表模板都放在子目录中（或者按 Hugo 的模板查找规则层层向上查找），而 404 模板只认 `layouts` 根目录，放在别处不会被采用。

```go-html-template {file="layouts/404.html"}
{{ 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 页面通过**文件名中的语言键**区分，例如德语、英语、法语各一份：

```tree
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 页面其实是一段空白或被服务器默认页面替换掉了。