需求

把 GitHub Pages 站点绑到自己的域名 toolgen.xyz 上，要求 HTTPS 强制开启。 过程中遇到两个典型问题：域名被另一个 GitHub 账号占用、CNAME 文件位置放错。 这篇记录完整流程和踩坑点。

第一步：DNS 配置（阿里云）

Pages 站点的域名解析要求：根域用 A 记录指向 GitHub Pages 的四个 IP， www 子域用 CNAME 指向 <username>.github.io。

# 根域（4 条 A 记录）
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

# www（1 条 CNAME）
www -> yourname.github.io

注意：根域不要用 CNAME 指向 github.io——根域 CNAME 与 DNSSEC/其他记录冲突， 解析不稳定。正确姿势是 A 记录。

第二步：CNAME 文件放对位置

关键坑：Pages 从发布目录（/docs 或 /）读取 CNAME 文件。 如果发布目录是 /docs，CNAME 必须放在 docs/CNAME， 放仓库根目录不生效。症状：Pages 状态 built 但 cname 一直为 None。

第三步：HTTPS 证书

CNAME 正确绑定后，GitHub 自动为域名签发 Let's Encrypt 证书并强制 HTTPS。 绑定后 API 里 https_certificate.state 会从 pending 变为 approved， 通常几分钟到几十分钟。证书每季度自动续期，无需人工干预。

第四步：跨账号域名占用迁移

最大的坑：域名之前绑定在另一个 GitHub 账号（比如旧账号）的 Pages 站点上， 新账号绑定会报错 The custom domain is already taken。

两种解法：

• 找回旧账号：重置密码登录旧账号，在仓库 Pages 设置里删除自定义域名（PUT API 传空 cname），释放占用。
• 域名所有权验证：如果旧账号无法访问，在 DNS 添加 TXT 记录 _github-pages-challenge-<username>.<domain> 验证域名归属， GitHub 验证后释放。

实测路径：通过重置旧账号密码 + 设备验证码登录，生成 PAT 后调用 PUT /repos/{owner}/{repo}/pages 传空 cname，HTTP 204 释放成功， 随后新账号 PUT cname 绑定成功，证书自动签发。

验证清单

• nslookup yourdomain.com 确认解析到 GitHub Pages 的 185.199.x.x
• API GET /repos/{owner}/{repo}/pages 的 cname 字段
• https://yourdomain.com 浏览器访问 + 锁图标（证书有效）