GitHub Pages 自定义域名的疑难解答

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

谁可以使用此功能？

GitHub Pages 可用于具有 GitHub Free 和 GitHub Free for organizations 的公共仓库，以及具有 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 文件。如果您在本地构建站点并将生成的文

然后，确保 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 错误

使用已使用CNAME、ALIAS、ANAME 或A DNS 记录正确配置的自定义域名的 GitHub Pages 站点可以通过 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 自定义域名”。