GitHub Pages 网站 404 错误排查 - GitHub 文档

排查 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 目录，则入口文件必须位于该分支的 /docs 目录中。

如果发布源是分支和目录的组合，入口文件必须位于该分支对应目录的根层级。例如，如果发布源是 main 分支下的 /docs 目录，则入口文件必须在该分支的 /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，导致链接失效，直至站点重建。
如果您为 GitHub Pages 网站使用了私有仓库，请检查您的 GitHub Pro、GitHub Team 或 GitHub Enterprise Cloud 订阅是否仍然有效。续费后，GitHub Pages 网站将自动重新部署。否则，您可以将仓库的可见性改为公开，以继续免费使用 GitHub Pages。

如果仍然收到 404 错误，请在 GitHub 社区讨论的 Pages 类别中发起讨论。