{"meta":{"title":"排查 GitHub Pages 网站的 404 错误","intro":"本指南将帮助你排查出现 404 错误的常见原因。","product":"GitHub Pages","breadcrumbs":[{"href":"/zh/pages","title":"GitHub Pages"},{"href":"/zh/pages/getting-started-with-github-pages","title":"开始"},{"href":"/zh/pages/getting-started-with-github-pages/troubleshooting-404-errors-for-github-pages-sites","title":"排查 404 错误"}],"documentType":"article"},"body":"# 排查 GitHub Pages 网站的 404 错误\n\n本指南将帮助你排查出现 404 错误的常见原因。\n\n## 排查 404 错误\n\n在本指南中，你将查找在构建 GitHub Pages 站点时出现 404 错误的常见原因。\n\n* [GitHub 的状态页](#githubs-status-page)\n* [DNS 设置](#dns-setup)\n* [浏览器缓存](#browser-cache)\n* [\n  `index.html` 文件](#indexhtml-file)\n* [目录内容](#directory-contents)\n* [自定义域](#custom-domain)\n* [Repository](#repository)\n\n### GitHub的“状态”页\n\n如果在构建 GitHub Pages 站点时出现 404 错误，请首先查看 GitHub 的[“状态”页](https://githubstatus.com)中是否有任何活动事件。\n\n### DNS 设置\n\n请确保 DNS 提供商正确设置了 GitHub 的 DNS 记录。 有关详细信息，请参阅“[管理 GitHub Pages 网站的自定义域](/zh/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site)”。\n\n### 浏览器缓存\n\n如果你的 GitHub Pages 站点是专用站点，并出现 404 错误，你可能需要清除浏览器的缓存。 有关清除缓存的更多信息，请参阅浏览器的文档。\n\n### `index.html` 文件\n\nGitHub Pages 将查找 `index.html` 文件，作为站点的入口文件。\n\n* 请确保 GitHub 上的站点存储库中有一个 `index.html` 文件。 有关详细信息，请参阅“[创建GitHub Pages网站](/zh/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site)”。\n\n* 入口文件必须位于所选发布源的顶层。 例如，如果发布源是 `/docs` 分支上的 `main` 目录，则入口文件必须位于名为 `/docs` 的分支上的 `main` 目录中。\n\n  如果发布源是分支和目录，则入口文件必须位于源分支上的源目录的顶层。 例如，如果发布源是 `/docs` 分支上的 `main` 目录，则入口文件必须位于名为 `/docs` 的分支上的 `main` 目录中。\n\n  如果发布源是 GitHub Actions 工作流，则部署的项目必须在项目的顶层包含入口文件。 可以选择使用 GitHub Actions 工作流在工作流运行时生成入口文件，而不是将入口文件添加到存储库。\n\n* `index.html` 文件的名称区分大小写。 例如，`Index.html` 无效。\n\n* 文件的名称应为 `index.html`，而不是 `index.HTML` 或其他变体。\n\n### 目录内容\n\n检查目录内容是否位于根目录中。\n\n### 自定义域\n\n如果使用的是自定义域，请确保已对其进行正确设置。 有关详细信息，请参阅“[关于自定义域名和 GitHub 页面](/zh/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)”。\n\n* `CNAME` 记录应始终指向 `<USER>.github.io` 或 `<ORGANIZATION>.github.io`，排除存储库名称。 有关如何创建正确记录的更多信息，请参阅 DNS 提供程序的文档。\n* 如果你能够访问登陆页面，但始终遇到断开的链接，可能是因为你之前没有自定义域名，或者正在恢复使用自定义域名。 在这种情况下，更改路由路径不会启动页面的重新生成。 建议的解决方案是确保在添加或移除自定义域名时自动重新生成站点。 这可能涉及配置提交作者和修改自定义域名设置。\n\n### Repository\n\n检查存储库是否满足以下要求。\n\n* 用于发布站点的分支必须是 `main` 分支或默认分支。\n* 存储库必须有一个提交，该提交由对存储库具有管理员权限的人员（如存储库所有者）推送到该存储库。\n* 如果将存储库的可见性从公共切换到私有（反之亦然），则会更改 GitHub Pages 站点的 URL，这将导致链接断开，直到重新生成站点。\n* 如果正在对 GitHub Pages 站点使用专用存储库，请检查 GitHub Pro、GitHub Team 或 GitHub Enterprise Cloud 订阅是否仍然处于活动状态。 如果续订计划，则将自动重新部署 GitHub Pages 站点。 否则，可以将存储库的可见性更改为公共，以继续免费使用 GitHub Pages。\n\n如果仍然收到 404 错误，请在 Pages 类别中开始 [GitHub Community 讨论](https://github.com/orgs/community/discussions/categories/pages)。"}