域名无法解析到 GitHub Pages，绝大多数情况不是 GitHub 坏了，而是 DNS 记录、CNAME 文件、域名状态或 HTTPS 证书这四个环节里至少有一个没对齐。 你看到的“无法访问”“404”“证书错误”，只是最终表现，真正的问题往往藏在域名注册商、DNS 服务商和 GitHub 仓库设置之间。
为什么域名无法解析到 GitHub Pages？先看三个硬条件
GitHub Pages 要接受你的自定义域名,需要同时满足三个硬条件。
域名解析到 GitHub Pages 需要满足哪些硬条件
- 仓库已经开启 Pages,并且发布源分支正确。
- 自定义域名已经填写在 GitHub Pages 设置里。
- DNS 记录把域名指向 GitHub Pages 的服务器或 CNAME 目标。
- 仓库根目录存在 CNAME 文件，内容只有域名，不带
https://和斜杠。 - 域名本身处于正常状态，没有过期、没有 ClientHold、没有未实名。
其中任何一项缺失，浏览器都可能报 DNS_PROBE_FINISHED_NXDOMAIN、404、SSL 错误，行业共识认为，先检查 GitHub 端设置，再检查 DNS 端,比反复刷新页面有效得多。
国内域名绑定 GitHub Pages 解析不生效的常见原因
国内注册商和 DNS 服务商有几类特殊限制。
- 域名未完成实名认证，据工信部数据，国内域名注册后需要实名核验,未通过可能被暂停解析。
- DNS 服务器被限制或劫持，部分小服务商对海外 IP 的 A 记录不友好。
- TTL 缓存过长，你改了记录，但本地和递归 DNS 还拿着旧数据。
- CNAME 与 A 记录冲突，同一个主机名不能同时存在 CNAME 和其他记录。
- Cloudflare 代理开启，橙色云朵会改变解析结果，导致 GitHub 证书签发失败。
如果你的域名在国内注册，先登录注册商控制台，查看域名状态是否为“正常”，再进入 DNS 解析列表,逐条核对记录类型和值。
GitHub Pages 自定义域名解析失败怎么办：从 DNS 到 HTTPS 逐项排查
下面按顺序排查，不要跳步,每一步都能缩小范围。
第一步：检查仓库 Pages 设置和 CNAME 文件
打开 GitHub 仓库，进入 Settings > Pages。
- 在 Custom domain 里填写你的域名，
www.example.com或example.com。 - 点击 Save，GitHub 会尝试进行 DNS 检查。
- 回到仓库根目录，确认有
CNAME
www.example.com。 - 如果你使用 GitHub Actions 部署，CNAME 文件可能被构建覆盖，把它放在
source分支或static目录，并在 workflow 中保留。
Custom domain 保存后提示“DNS check unsuccessful”，说明 GitHub 没有查到正确的解析记录，此时不要反复点击，先去 DNS 服务商改记录。
第二步：核对 DNS 记录类型和值
GitHub Pages 官方推荐两种方式。
| 域名类型 | 记录类型 | 主机记录 | 记录值 |
|---|---|---|---|
| 根域名 example.com | A | 199.108.153 | |
| 根域名 example.com | A | 199.109.153 | |
| 根域名 example.com | A | 199.110.153 | |
| 根域名 example.com | A | 199.111.153 | |
| 子域名 www.example.com | CNAME | www | username.github.io |
注意：username.github.io 要换成你的 GitHub 用户名，CNAME 值不要带 https://，不要带路径，根域名不能直接 CNAME 到 username.github.io，因为 DNS 协议不允许 apex 域名使用 CNAME，部分 DNS 服务商提供 ALIAS 或 ANAME，可以用，但本质仍是解析到 GitHub 的 IP。
改完后,用命令验证：
dig example.com +noall +answer nslookup -type=CNAME www.example.com
Windows 可以运行 nslookup example.com，如果返回的 IP 不是 185.199.108.153 到 185.199.111.153,说明解析没生效或写错了。
第三步：等待 TTL 并清理缓存
DNS 修改不是瞬间全球生效，TTL 决定旧记录被缓存多久，常见 TTL 是 600 秒、3600 秒。
- 在 DNS 服务商把 TTL 临时改小,600。
- 刷新本地缓存：Windows 用
ipconfig /flushdns，macOS 用sudo dscacheutil -flushcache。 - 用公共 DNS 测试：
nslookup example.com 8.8.8.8。 - 使用 DNS 检测工具查看多地结果。
业内专家指出，DNS 传播延迟主要受 TTL 影响，改完记录后不必反复重装系统，如果公共 DNS 已经返回正确 IP，但你的电脑还不行，问题就在本地缓存或路由器 DNS。
第四步：处理 HTTPS 证书和 Enforce HTTPS
DNS 生效后，GitHub 才会为自定义域名签发 Let's Encrypt 证书,证书签发通常需要几分钟到几小时。
- 进入 Settings > Pages，勾选 Enforce HTTPS。
- 如果证书一直 pending，先取消 Custom domain,再重新填写。
- 如果使用 Cloudflare，把代理状态改为 DNS only（灰云），等 GitHub 签发证书后再决定是否开启代理。
- Cloudflare 的 SSL/TLS 模式不要用 Flexible，否则会重定向循环，用 Full 或 Full (strict)。
GitHub Pages 域名解析和 CNAME 记录哪个更好用？不同场景的选择
很多人纠结 A 记录和 CNAME，它们不是二选一,而是按域名类型分工。
根域名用 A 记录，子域名用 CNAME
- 根域名
example.com：用 4 条 A 记录指向 GitHub Pages IP。 - 子域名
www.example.com：用 CNAME 指向username.github.io。 - 如果你想让
www跳转到根域名，可以在 DNS 服务商设置 URL 转发，或者在 GitHub Pages 设置里把www设为主域名,再让根域名跳转。
对比一下：
| 场景 | 推荐记录 | 原因 |
|---|---|---|
| 根域名 | A 记录 | DNS 协议不支持根域名 CNAME |
| 子域名 | CNAME | 跟随 GitHub 的 IP 变化 |
| 使用 Cloudflare | 先灰云 CNAME | 避免代理干扰证书 |
| 国内访问 | A 记录 + 公共 DNS | 减少解析异常 |
免费域名解析到 GitHub Pages 靠谱吗？国内注册商与 Cloudflare 场景
免费域名通常指 .tk、.ml 等免费顶级域，或者免费二级域名，它们可以解析到 GitHub Pages,但有几个坑。
- 免费域名可能被滥用,部分浏览器和邮件服务会拦截。
- 免费域名商可能不提供完整的 DNS 管理，无法添加 4 条 A 记录。
- HTTPS 证书签发可能因为域名信誉问题失败。
- 国内访问 GitHub Pages 本身不稳定,免费域名不会改善连通性。
如果你使用国内注册商，域名需要实名，解析到 GitHub Pages 不需要备案，但国内访问速度取决于网络环境，想让解析更稳，可以把 DNS 托管到 Cloudflare 或国内公共 DNS,再按上面的记录配置。
那些容易被忽略的细节：从 www 到 CNAME 冲突
排查到最后,问题往往在细节。
CNAME 文件与仓库分支
GitHub Pages 的 CNAME 文件必须位于发布源，如果你用 main 分支的 /docs 目录发布，CNAME 要放在 docs/CNAME，如果你用 GitHub Actions，构建产物会覆盖仓库文件，需要在 workflow 里加入步骤，把 CNAME 写回 public 或 dist 目录。
DNS 记录冲突：多个 A 记录和 CNAME 不能共存
同一个主机名不能同时有 CNAME 和其他记录,检查是否残留：
www同时有 CNAME 和 A 记录。- 同时有 A 记录和 CNAME。
- 有 AAAA 记录指向错误 IPv6。
- 有 TXT 记录不影响解析,但可能被误认为冲突。
删除冲突记录,只保留需要的类型。
域名注册商未实名或 DNS 服务器故障
国内注册商要求实名认证，未实名会暂停解析，域名过期或处于 ClientHold 状态，同样无法解析，登录注册商控制台，查看域名状态，DNS 服务器本身故障，换用公共 DNS，5.5.5、29.29.29、8.8.8。
Q&A：域名无法解析到 GitHub Pages 怎么办？
为什么 DNS 已经改了，ping 还是旧 IP？
本地 DNS 缓存和递归 DNS 缓存没有过期，TTL 未到时间，旧记录仍在，用 nslookup example.com 8.8.8.8 测试公共 DNS，如果公共 DNS 返回新 IP，说明全球解析正在生效，只需等待,刷新本地缓存后重试。
GitHub Pages 显示 404 但 DNS 已生效？
DNS 生效只代表域名找到了 GitHub 服务器，不代表仓库有内容，检查发布分支是否有 index.html，Pages 是否构建成功，Custom domain 是否保存，如果仓库是私有库，确认 GitHub 计划支持 Pages,公开库通常没有这个问题。
使用 Cloudflare 后域名无法解析到 GitHub Pages？
Cloudflare 代理会隐藏真实 IP，Let's Encrypt 证书签发可能失败，把记录改为 DNS only，等待 GitHub 签发证书，SSL/TLS 模式设为 Full 或 Full (strict)，不要用 Flexible，删除多余的 A 记录，只保留 CNAME 指向 username.github.io，证书签发成功后,再决定是否开启代理。
域名无法解析到 GitHub Pages，核心就是让 GitHub 端、DNS 端和域名状态三者一致。 按“仓库设置、DNS 记录、TTL 缓存、HTTPS 证书”的顺序排查,多数问题都能定位到具体记录或文件。