添加404错误页面

别担心，您没有进入一个缺失的页面。这个页面是关于404错误页面以及如何将其添加到您的已发布站点的。

什么是404错误页面？

如果网络服务器无法找到URL的页面，它会向浏览器返回404状态代码（而不是正常的200状态代码）。这可能发生在访问者从站点内部或搜索引擎点击损坏的链接，或者在浏览器地址栏中误输入URL时。

与向访问者显示空白页面或低级别错误消息不同，网络服务器通常会显示404错误页面的内容（以下简称404页面）。

为了提供404页面，网络服务器会查找位于已发布站点根目录下的文件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页面

只有当playbook中的site.url键具有值时，Antora才会生成404页面。假设是，如果站点URL已指定，则该站点将被发布到Web服务器。

site.url键的值可以是绝对URL或根相对路径，如在站点URL页面中解释的那样。路径段可以是非空的，这将在下一节中讨论。

如果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）提供站点文件时。

以下是设置此配置所需的三个步骤。我们将假设域名为example.com，子路径为site-a，Web服务器为nginx。

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

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

    或者使用根相对路径：

    site:
  url: /site-a
    playbook中定义的站点URL 必须 包含子路径。否则，404页面中的URL将不正确（例如，CSS文件的URL）。

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

    location /site-a/ {
  error_page 404 /site-a/404.html;
}
    调整子路径位置以匹配您站点的子路径。

  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_。