排查 GitHub Pages 网站的 404 错误

本指南将帮助您排查您可能看到 404 错误的常见原因。

谁可以使用此功能？

GitHub Pages 可用于具有 GitHub Free 和 GitHub Free for organizations 的公共仓库，以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。有关更多信息，请参阅“GitHub 的计划”。

从 2024 年 6 月 30 日起，所有 GitHub Pages 构建都将使用 GitHub Actions。无需进行其他更改，但必须在您的仓库中启用 GitHub Actions 才能继续构建。有关启用 GitHub Actions 的更多信息，请参阅“管理仓库的 GitHub Actions 设置”。

排查 404 错误

在本指南中，您将找到在构建 GitHub Pages 网站时可能看到 404 错误的常见原因。

GitHub 状态页面

如果您在构建 GitHub Pages 网站时看到 404 错误，请先查看 GitHub 的 状态页面，了解是否有任何活动事件。

DNS 设置

确保 GitHub 的 DNS 记录已在您的 DNS 提供商处正确设置。有关更多信息，请参阅“管理 GitHub Pages 网站的自定义域名”。

浏览器缓存

如果您的 GitHub Pages 网站是私有的，并且您看到 404 错误，您可能需要清除浏览器的缓存。有关清除缓存的更多信息，请参阅浏览器的文档。

index.html 文件

GitHub Pages 将查找 index.html 文件作为您网站的入口文件。

  • 确保您在 GitHub 上的网站仓库中有一个 index.html 文件。有关更多信息，请参阅“创建 GitHub Pages 网站”。

  • 入口文件必须位于您选择的发布源的顶层。例如，如果您的发布源是 main 分支上的 /docs 目录，则您的入口文件必须位于名为 main 的分支上的 /docs 目录中。

    如果您的发布源是分支和目录，则入口文件必须位于源分支上的源目录的顶层。例如，如果您的发布源是 main 分支上的 /docs 目录，则您的入口文件必须位于名为 main 的分支上的 /docs 目录中。

    如果您的发布源是 GitHub Actions 工作流，则您部署的工件必须包含位于工件顶层的入口文件。您可以选择在工作流运行时让您的 GitHub Actions 工作流生成您的入口文件，而不是将入口文件添加到您的仓库中。

  • index.html 文件的名称区分大小写。例如，Index.html 将不起作用。

  • 文件名称应为 index.html，而不是 index.HTML 或任何其他变体。

目录内容

检查您的目录内容是否在根目录中。

自定义域名

如果您使用的是自定义域名，请确保其设置正确。有关更多信息，请参阅“关于自定义域名和 GitHub Pages”。

  • CNAME 记录应始终指向 <USER>.github.io 或 <ORGANIZATION>.github.io，不包括仓库名称。有关如何创建正确记录的更多信息，请参阅您的 DNS 提供商的文档。
  • 如果您能够访问您的登录页面，但在整个页面中遇到链接失效，这可能是因为您之前没有自定义域名，或者正在从使用自定义域名恢复。在这种情况下，更改路由路径不会启动页面的重新构建。建议的解决方案是确保在添加或删除自定义域名时，您的网站会自动重新构建。这可能涉及配置提交作者并修改自定义域名设置。

仓库

检查您的仓库是否满足以下要求。

  • 您用于发布网站的分支必须是 main 或默认分支。
  • 仓库必须由具有仓库管理员权限的人员（例如仓库所有者）提交到仓库。
  • 将仓库的可见性从公开更改为私有或反之亦然将更改您的 GitHub Pages 网站的 URL，这会导致链接失效，直到网站重新构建。

如果您仍然收到 404 错误，请在 Pages 类别中启动 GitHub 社区讨论。