排查 GitHub Pages 站点的 404 错误

本指南将帮助你排查出现 404 错误的常见原因。

谁可以使用此功能？

GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共存储库，以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和专用存储库。

排查 404 错误

在本指南中，你将查找在构建 GitHub Pages 站点时出现 404 错误的常见原因。

GitHub的“状态”页

如果在构建 GitHub Pages 站点时出现 404 错误，请首先查看 GitHub 的“状态”页中是否有任何活动事件。

浏览器缓存

如果你的 GitHub Pages 站点是专用站点，并出现 404 错误，你可能需要清除浏览器的缓存。 有关清除缓存的更多信息，请参阅浏览器的文档。

index.html 文件

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

  • 请确保 GitHub Enterprise Server 上的站点存储库中有一个 index.html 文件。 有关详细信息，请参阅“创建 GitHub Pages 站点”。

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

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

    如果发布源是 GitHub Actions 工作流，则部署的项目必须在项目的顶层包含入口文件。 可以选择使用 GitHub Actions 工作流在工作流运行时生成入口文件，而不是将入口文件添加到存储库。

  • index.html 文件的名称区分大小写。 例如，Index.html 无效。

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

目录内容

检查目录内容是否位于根目录中。

存储库

检查存储库是否满足以下要求。

  • 用于发布站点的分支必须是 main 分支或默认分支。
  • 存储库必须有一个提交，该提交由对存储库具有管理员权限的人员（如存储库所有者）推送到该存储库。
  • 如果将存储库的可见性从公共切换到私有（反之亦然），则会更改 GitHub Pages 站点的 URL，这将导致链接断开，直到重新生成站点。
  • 如果正在对 GitHub Pages 站点使用专用存储库，请检查 GitHub Pro、GitHub Team 或 GitHub Enterprise Cloud 订阅是否仍然处于活动状态。 如果续订计划，则将自动重新部署 GitHub Pages 站点。 否则，可以将存储库的可见性更改为公共，以继续免费使用 GitHub Pages。

如果仍然收到 404 错误，请在 Pages 类别中开始 GitHub Community 讨论。