自定义域和 GitHub Pages 疑难解答

您可以检查常见错误，以解决与 GitHub Pages 站点的自定义域或 HTTPS 相关的问题。

谁可以使用此功能？

GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共存储库，以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和专用存储库。 有关详细信息，请参阅“GitHub 的计划”。

GitHub Pages 现在使用 GitHub Actions 来执行 Jekyll 构建。 使用分支作为构建源时，如果要使用内置的 Jekyll 工作流，则必须在存储库中启用 GitHub Actions。 或者，如果 GitHub Actions 不可用或已禁用，则将 .nojekyll 文件添加到源分支的根目录将绕过 Jekyll 构建过程并直接部署内容。 有关 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 提供商，看他们是否提供域名转发服务。

确保您的站点没有：

  • 使用多个 apex 域。 例如，example.com 和 anotherexample.com。

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

  • 同时使用 apex 域和自定义子域。 例如，example.com 和 docs.example.com。

    一个例外是 www 子域。 如果配置正确， www 子域将自动重定向到 apex 域。 有关详细信息，请参阅“管理 GitHub Pages 站点的自定义域”。

警告：我们强烈建议勿使用通配符 DNS 记录，例如 *.example.com。 即使验证域，这些记录也会立即面临域接管风险。 例如，如果验证 example.com，这会阻止某人使用 a.example.com，但他们仍可以接管 b.a.example.com（由通配符 DNS 记录所涵盖）。 有关详细信息，请参阅“验证 GitHub Pages 的自定义域”。

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

HTTPS 错误

可以通过 HTTPS 访问使用正确配置了 CNAME、ALIAS、ANAME 或 A DNS 记录的自定义域的 GitHub Pages 站点。 有关详细信息，请参阅“使用 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 的自定义域”。