自定义域名（docs.xshayncka.dev）¶

phase-barrier 官方文档站托管在 GitHub Pages，当前启用自定义域名：

正式地址：https://docs.xshayncka.dev/（2026-09-06 启用：DNS / CNAME / HTTPS 均已配置完成）
默认地址：https://xuqing0415.github.io/phase-barrier/（GitHub Pages 默认地址，配置自定义域名后自动 301 重定向）

本文记录如何把 docs.xshayncka.dev 指向 GitHub Pages，并提供自动化检查脚本；迁移新域名或回滚时可参照本文步骤。DNS 校验通过前不要提交 CNAME 文件，否则 GitHub Pages 会因无法校验域名而暂时中断默认地址访问。

工作原理¶

MkDocs 会把 docs/ 目录下除 Markdown 外的文件原样复制到站点根目录。因此只需在仓库内维护 docs/CNAME（内容为一行域名），部署 workflow （.github/workflows/docs.yml）推送到 gh-pages 分支后，GitHub Pages 读取站点根目录的 CNAME 即自动应用自定义域名。

前置检查（约 2 分钟）¶

1. 确认域名已注册且公网可解析（替换为你的域名）：
```
nslookup xshayncka.dev 8.8.8.8
```
  apex 返回 NXDOMAIN 表示域名未注册或未接入公网 DNS，需先到注册商完成注册， GitHub Pages 无法为不存在的域名签发证书。
1. 确认 docs. 子域当前无冲突记录：
```
Resolve-DnsName docs.xshayncka.dev -ErrorAction SilentlyContinue
```
  期望无记录（可新建 CNAME）；若已有记录，先确认归属再覆盖。

配置步骤（约 10 分钟）¶

DNS 解析：到域名服务商添加一条 CNAME 记录

主机记录	类型	记录值
`docs`	CNAME	`xuqing0415.github.io`

添加 CNAME 文件：在仓库根目录执行

echo docs.xshayncka.dev > docs/CNAME
git add docs/CNAME
git commit -m "chore: enable docs.xshayncka.dev custom domain"
git push origin main

docs.yml 部署完成后，用下面命令确认站点内已带 CNAME：

python scripts/check_custom_domain.py

GitHub Pages 设置：仓库 Settings -> Pages -> Custom domain 填入 docs.xshayncka.dev 并保存。GitHub 会校验 DNS 并为该域名签发 HTTPS 证书（通常几分钟，最长约 24 小时）。
强制 HTTPS：证书签发成功后勾选 Enforce HTTPS。
验证：

curl -I https://docs.xshayncka.dev/plugin-status/   # 期望 HTTP 200
python scripts/check_custom_domain.py --strict           # 期望 exit 0

自动化检查¶

scripts/check_custom_domain.py（纯标准库）检查 docs/CNAME 是否存在且内容与期望域名一致：

python scripts/check_custom_domain.py            # 未配置时打印警告但 exit 0
python scripts/check_custom_domain.py --strict   # 未配置 / 配置错误时 exit 1
python scripts/check_custom_domain.py --cname path/to/CNAME --domain example.com

默认非阻塞：CI（docs.yml）每次构建都会运行一次，未配置时仅输出 ::warning::，不影响部署。
--strict 供本地验收 / 发布前检查使用：未配置或内容不一致时返回非零。
该检查只验证仓库内 CNAME 文件；真实域名解析与证书签发由 GitHub Pages 负责，需在网页端确认。

回滚¶

删除 docs/CNAME 并推送，下一次 docs.yml 部署会自动恢复 https://xuqing0415.github.io/phase-barrier/ 访问；如需同时移除 GitHub Pages 设置里的自定义域名，在 Settings -> Pages 中清除即可。

故障排查¶

现象	原因与处理
`curl https://docs.xshayncka.dev` 报 DNS 解析失败	CNAME 未生效：检查 DNS 记录与解析传播（`nslookup docs.xshayncka.dev`）
GitHub Pages 提示 "domain does not resolve"	DNS 记录值写错或指向了 `github.io` 之外的地址
配置后默认地址 `xuqing0415.github.io/...` 暂时 404	自定义域名证书签发中，属正常现象，等待完成
`check_custom_domain.py --strict` 退出 1	仓库内尚无 `CNAME` 或内容与期望域名不一致
`nslookup xshayncka.dev 8.8.8.8` 返回 NXDOMAIN	域名未注册或未接入公网 DNS：先完成注册与实名，再继续后续步骤

状态（截至 2026-09-06）：docs.xshayncka.dev 已启用——DNS CNAME、docs/CNAME、 GitHub Pages 自定义域名与 HTTPS 证书均配置完成，https://docs.xshayncka.dev/ 返回 200，旧默认地址 301 重定向至新域名。