排查 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，这将导致断开的链接，直到站点重新构建。
- 如果您正在使用 GitHub Pages 站点的私有仓库，请检查您的 GitHub 专业版、GitHub 团队版或 GitHub Enterprise Cloud 订阅是否仍然有效。如果您续订了套餐，GitHub Pages 站点将自动重新部署。否则，您可以将仓库的可见性更改为公共以继续免费使用 GitHub Pages。
如果您仍然收到 404 错误，请在 Pages 类别中启动GitHub 社区讨论。