添加 404 错误页面

别担心，你还没有找到缺的那一页。这个页面是关于 404 错误页面以及如何将它添加到您发布的网站。

什么是404错误页面

如果 Web 服务器无法找到 URL 的页面，它会向浏览器返回 404 状态代码（而不是正常的 200 状态代码）。这可能是因为访问者从站内或搜索引擎点击了一个破损的链接或在浏览器地址栏中错误地键入了 URL。

与其向访问者显示一个空白页面或低级别的错误消息，Web 服务器通常会显示 404 错误页面的内容（在此处称为 404 页面）。

要提供 404 页面，Web 服务器查找位于已发布站点根目录下的 404.html 文件。此文件的内容用于代替访问者将看到的 HTML 。访问者不会被重定向到另一个页面，因此原始 URL 仍然在浏览器地址栏中可见。

现在让我们学习如何定义 404 页面并将其添加到您的 Antora 网站中。

定义404页面

在 Antora 网站中，404 页面使用 UI 提供的布局模板创建。为了使其正常工作，UI 必须定义一个名为 404 的布局模板，位于 layouts/404.hbs 路径下。Antora 使用此模板生成 404.html 文件，然后将其输出到已发布站点的根目录。

如果您使用或扩展默认 UI，则已经为 404 页面提供了布局模板。

404 布局模板是使用缩减的 UI 模型编译的，该模型不包括任何关于当前页面（因为没有页面）的信息，除了 page.title 和 page.layout 。该模板可以访问 UI 模型中的所有其他变量，例如 uiRootPath 和 site.components 。

与常规页面不同，404 模板中的 uiRootPath 和 siteRootPath 模板变量是根相对路径。这是为了使 404 页面在由服务器服务时能够正确工作。这是因为 404 页的内容是从访问者最初请求的任何 URL 处提供的。

激活404页面

Antora 仅在 playbook 中的 site.url 键具有值时生成 404 页面。假设如果指定了站点 URL ，则该站点将被发布到 Web 服务器上。

site.url 键的值可以是绝对 URL 或根相对路径，如站点 URL 页面中所解释的。路径段可以是非空的，在下一节中将对其进行说明。

IMPORTANT

如果 Antora 在 UI 包（或补充 UI 包）中没有找到具有名称 404 的布局模板，则不会为您的站点生成 404 页面（即使在 playbook 中设置了 site.url 键）。

在发布到子路径时配置404页面

通常情况下，您无需做其它任何事情即可使 404 页面正常工作。Web 服务器会自动获取位于已发布站点根目录下的 404.html 文件，并在访问者跳转到缺失的页面时使用它。

但是，如果您将站点发布到域的子路径中（例如 https://example.org/site-a ），则需要进行其它配置。

当您的站点 URL 包含路径段时，您的站点的 404 页面将不再位于 Web 服务器根目录下。相反，它将位于一个子路径下，与其他文件在一起。问题是，Web 服务器不知道这个子路径的重要性（也就是说，它不知道子路径是离散站点的边界）。因此，Web 服务器将不知道在缺失页面的位置上使用这个 404 页面。因此，我们必须告诉它这样做。我们必须配置 Web 服务器在为站点提供文件时使用子路径下的 404 页面（例如 /site-a/404.html ），而不是默认位置（即 /404.html ）的 404 页面。

这里有三个步骤需要完成设置。我们假设域是 example.com ，子路径是 site-a ，Web 服务器是 nginx 。

  1. 在 playbook 文件中使用绝对 URL 定义带有子路径的 site.url ：

    site:
  url: https://example.com/site-a

    或者相对根路径：

    site:
  url: /site-a
    IMPORTANT

    剧本(playbook)中定义的站点 URL 必须包含子路径。否则，404 页面中的 URL 将不正确(例如，CSS 文件的 URL )。

  2. 配置 nginx 使用子路径文件夹中的 404.html 来处理该子路径下任何缺失的 URL：

    location /site-a/ {
  error_page 404 /site-a/404.html;
}
    NOTE

    调整子路径位置以匹配站点的子路径。

  3. 将 Antora 生成的站点文件复制到 web 服务器根目录下的子路径下：

    rsync -r --delete build/site/ /usr/share/nginx/html/site-a

    换句话说，子路径文件夹必须位于 web 服务器根目录或虚拟主机的根目录。

Antora 演示就是这种配置的一个例子（除非 GitLab Pages 服务器会自动为您映射子路径下的 404 页面）。请查看 antora.gitlab.io/demo/docs-site/component-b/2.0/no-such-page.html 。请注意 CSS 文件的 URL 是根相对路径 /demo/docs-site/css/site.css 。