排查 GitHub Pages 网站的 404 错误

排查 404 错误

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

•         [GitHub 的状态页](#githubs-status-page)
  

•         [浏览器缓存](#browser-cache)
  

•         [
          `index.html` 文件](#indexhtml-file)
  

•         [目录内容](#directory-contents)
  

•         [Repository](#repository)
  

GitHub的“状态”页

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

浏览器缓存

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

          `index.html` 文件

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

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

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

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

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

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

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

目录内容

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

Repository

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

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

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