排查自定义域名和 GitHub Pages 的问题

您可以检查常见错误以解决 GitHub Pages 网站的自定义域名或 HTTPS 问题。

谁可以使用此功能？

GitHub Pages 在使用 GitHub Free 和 GitHub Free for organizations 的公共仓库中可用，在使用 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库中可用。有关更多信息，请参阅“GitHub 的计划”。

从 2024 年 6 月 30 日起，所有 GitHub Pages 构建都将使用 GitHub Actions。无需进行其他更改，但必须在您的仓库中启用 GitHub Actions 才能继续构建。有关启用 GitHub Actions 的更多信息，请参阅“管理仓库的 GitHub Actions 设置”。

本文内容

CNAME 错误

如果您是从自定义 GitHub Actions 工作流发布，则会忽略任何 CNAME 文件，并且不需要该文件。

如果您是从分支发布，则自定义域名存储在发布源根目录中的 CNAME 文件中。您可以通过仓库设置或手动添加或更新此文件。有关更多信息，请参阅“管理 GitHub Pages 网站的自定义域名”。

为了确保您的网站在正确的域名下渲染，请确保您的 CNAME 文件仍然存在于仓库中。例如，许多静态网站生成器会强制推送到您的仓库，这可能会覆盖您在配置自定义域名时添加到仓库的 CNAME 文件。如果您在本地构建网站并将生成的 文件推送到 GitHub，请确保首先将添加 CNAME 文件的提交拉取到您的本地仓库，这样该文件将包含在构建中。

然后，确保 CNAME 文件格式正确。

  • CNAME 文件名必须全部大写。
  • CNAME 文件只能包含一个域名。要将多个域名指向您的网站，您必须通过您的 DNS 提供商设置重定向。
  • CNAME 文件必须仅包含域名。例如，www.example.com、blog.example.com 或 example.com。
  • 域名在所有 GitHub Pages 网站中必须是唯一的。例如，如果另一个仓库的 CNAME 文件包含 example.com，则您不能在您的仓库的 CNAME 文件中使用 example.com。

DNS 配置错误

如果您在将网站的默认域名指向您的自定义域名时遇到问题，请联系您的 DNS 提供商。

您还可以使用以下方法之一来测试您的自定义域名的 DNS 记录是否配置正确

不支持的自定义域名

如果您的自定义域名不受支持，您可能需要将您的域名更改为支持的域名。您也可以联系您的 DNS 提供商，看看他们是否提供域名转发服务。

确保您的网站不

  • 使用多个顶层域名。例如，example.com 和 anotherexample.com。

  • 使用多个 www 子域名。例如，www.example.com 和 www.anotherexample.com。

  • 使用顶层域名和自定义子域名。例如，example.com 和 docs.example.com。

    唯一的例外是 www 子域名。如果配置正确，www 子域名会自动重定向到顶层域名。有关更多信息，请参阅“管理 GitHub Pages 站点的自定义域名”。

警告：我们强烈建议您不要使用通配符 DNS 记录，例如 *.example.com。这些记录会使您面临域名被劫持的风险，即使您已验证域名。例如，如果您验证了 example.com，这将阻止其他人使用 a.example.com，但他们仍然可以接管 b.a.example.com（它受通配符 DNS 记录的保护）。有关更多信息，请参阅“验证 GitHub Pages 的自定义域名”。

有关支持的自定义域名的列表，请参阅“关于自定义域名和 GitHub Pages”。

HTTPS 错误

使用自定义域名的 GitHub Pages 网站，如果正确配置了 CNAME、ALIAS、ANAME 或 A DNS 记录，则可以通过 HTTPS 访问。有关更多信息，请参阅“使用 HTTPS 保护 GitHub Pages 网站”。

配置自定义域名后，您的网站可能需要长达一个小时才能通过 HTTPS 访问。更新现有 DNS 设置后，您可能需要从网站的存储库中删除并重新添加自定义域名，以触发启用 HTTPS 的过程。有关更多信息，请参阅“管理 GitHub Pages 站点的自定义域名”。

如果您使用的是证书颁发机构授权 (CAA) 记录，则至少必须存在一条值为 letsencrypt.org 的 CAA 记录，才能通过 HTTPS 访问您的网站。有关更多信息，请参阅 Let's Encrypt 文档中的“证书颁发机构授权 (CAA)”。

Linux 上的 URL 格式

如果您的网站 URL 包含以连字符开头或结尾，或包含连续连字符的用户名或组织名称，那么使用 Linux 浏览的人员在尝试访问您的网站时会收到服务器错误。要解决此问题，请更改您的 GitHub 用户名以删除非字母数字字符。有关更多信息，请参阅“更改您的 GitHub 用户名”。

浏览器缓存

如果您最近更改或删除了自定义域名，并且无法在浏览器中访问新 URL，则可能需要清除浏览器缓存才能访问新 URL。有关清除缓存的更多信息，请参阅浏览器的文档。

域名已被占用

如果您尝试使用自定义域名，但显示该域名已被使用，您可以先验证该域名，使其可供您使用。有关更多信息，请参阅“验证您的 GitHub Pages 自定义域名”。