自定义域和 GitHub Pages 疑难解答
您可以检查常见错误,以解决与 GitHub Pages 站点的自定义域或 HTTPS 相关的问题。
GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共仓库,以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。 更多信息请参阅“GitHub 的产品”。
CNAME 错误
自定义域存储在发布源的根目录下的 CNAME 文件中。 您可以通过仓库设置或手动添加或更新此文件。 更多信息请参阅“管理 GitHub Pages 网站的自定义域。
要让您的站点呈现在正确的域中,请确保您的 CNAME 文件仍存在于仓库中。 例如,许多静态站点生成器会强制推送到您的仓库,这可能会覆盖在配置自定义域时添加到仓库中的 CNAME 文件。 如果您在本地构建站点并将生成的文件推送到 GitHub,请确保先将添加 CNAME 文件的提交拉取到本地仓库,使该文件纳入到构建中。
然后,确保 CNAME 文件格式正确。
- CNAME 文件名必须全部大写。
- CNAME 文件只能包含一个域。 要将多个域指向您的站点,必须通过 DNS 提供程序设置重定向。
- CNAME 条目必须是裸域。 例如,
www.example.com
、blog.example.com
或example.com
。 - CNAME 条目只能在 GitHub 上使用一次。 例如,如果另一个仓库的 CNAME 文件包含
example.com
,则不能在您仓库的 CNAME 文件中使用example.com
。
DNS 配置错误
如果将站点的默认域指向自定义域时遇到问题,请联系 DNS 提供商。
您还可以测试自定义域的 DNS 记录是否配置正确。 更多信息请参阅“管理 GitHub Pages 网站的自定义域。
自定义域名不受支持
如果您的自定义域不受支持,则可能需要将您的域更改为受支持的域。 也可以联系您的 DNS 提供商,看他们是否提供域名转发服务。
确保您的站点没有:
- 使用多个 apex 域。 例如,同时使用
example.com
和anotherexample.com
。 - 使用多个
www
子域。 例如,同时使用www.example.com
和www.anotherexample.com
。 - 同时使用 apex 域和自定义子域。 例如,同时使用
example.com
和docs.example.com
。
警告:我们强烈建议不要使用通配符 DNS 记录,例如
*.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。 有关清除缓存的更多信息,请参阅浏览器的文档。