Skip to main content

自定义域和 GitHub Pages 疑难解答

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

GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共仓库,以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。 有关详细信息,请参阅“GitHub 的产品”。

CNAME 错误

如果从自定义 GitHub Actions 工作流进行发布,则忽略且无需任何 CNAME 文件。

如果从分支进行发布,自定义域存储在发布源根目录下的 CNAME 文件中。 您可以通过仓库设置或手动添加或更新此文件。 有关详细信息,请参阅“为你的 GitHub Pages 站点管理自定义域”。

要让站点呈现在正确的域中,请确保 CNAME 文件仍存在于存储库中。 例如,许多静态站点生成器会强制推送到存储库,这可能会覆盖在配置自定义域时添加到存储库的 CNAME 文件。 如果在本地构建站点并将生成的文件推送到 GitHub,请确保先将添加 CNAME 文件的提交拉取到本地存储库,使该文件包含在构建中。

然后,请确保 CNAME 文件的格式正确。

  • CNAME 文件名必须全部大写。
  • CNAME 文件只能包含一个域。 要将多个域指向您的站点,必须通过 DNS 提供程序设置重定向。
  • CNAME 文件必须仅包含域名。 例如,www.example.comblog.example.comexample.com
  • 域名在所有 GitHub Pages 站点中必须是唯一的。 例如,如果另一个存储库的 CNAME 文件包含 example.com,则不能在存储库的 CNAME 文件中使用 example.com

DNS 配置错误

如果将站点的默认域指向自定义域时遇到问题,请联系 DNS 提供商。

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

自定义域名不受支持

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

确保您的站点没有:

  • 使用多个 apex 域。 例如,example.comanotherexample.com

  • 使用多个 www 子域。 例如,www.example.comwww.anotherexample.com

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

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

警告:强烈建议勿使用通配符 DNS 记录,例如 *.example.com。 通配符 DNS 记录将允许任何人在你的其中一个子域上托管 GitHub Pages 站点,即使这些子域会进行验证也是如此。 有关详细信息,请参阅“验证 GitHub Pages 的自定义域”。

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

HTTPS 错误

可以通过 HTTPS 访问使用正确配置了 CNAMEALIASANAMEA 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。 有关清除缓存的更多信息,请参阅浏览器的文档。