排查 GitHub Pages 站点的 404 错误

排查 404 错误

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

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

请确保 DNS 提供商正确设置了 GitHub 的 DNS 记录。有关详细信息，请参阅“管理 GitHub Pages 站点的自定义域”。

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

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 页面”。

CNAME 记录应始终指向 <USER>.github.io 或 <ORGANIZATION>.github.io，排除存储库名称。有关如何创建正确记录的更多信息，请参阅 DNS 提供程序的文档。
如果你能够访问登陆页面，但始终遇到断开的链接，可能是因为你之前没有自定义域名，或者正在恢复使用自定义域名。在这种情况下，更改路由路径不会启动页面的重新生成。建议的解决方案是确保在添加或移除自定义域名时自动重新生成站点。这可能涉及配置提交作者和修改自定义域名设置。

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

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

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