跳到主要内容
基础知识

GitHub Pages 自定义域名 SSL 怎么配?从 DNS 解析到证书签发的完整实操与排错

github pages 自定义域名ssl — GitHub Pages 自定义域名 SSL 怎么配?从 DNS 解析到证书签发的完整实操与排错
核心结论

GitHub Pages 的自定义域名 SSL 证书由 GitHub 通过 Let's Encrypt 免费自动签发,有效期 90 天、到期前约 30 天自动续期;你只需把域名 A 记录指向 185.199.108.153~185.199.111.153 并在 Settings → Pages 勾选 Enforce HTTPS,通常 15 分钟内生效,官方给出的上限是 24 小时。 用一条命令就能查签发状态:gh api repos/OWNER/REPO/pages --jq '.https_certificate.state',返回 approved 表示证书已下发;也可用 gh api -X PUT repos/OWNER/REPO/pages -F https_enforced=true 直接开启强制 HTTPS。 签发失败最常见的两个原因:CAA 记录没有放行 letsencrypt.org(dig CAA example.com +short 可验证),以及域名已被其他 GitHub 仓库绑定导致 CNAME already taken。 GitHub Pages 不支持上传自有证书,也不签发通配符证书;需要 OV/EV 或 *.example.com 时,必须前置 Cloudflare(Business 起可上传)或自建 Nginx + certbot 反代。 验证是否真的生效看三处:curl -sI https://example.com 返回 200 且带 strict-transport-security: max-age=31556952、openssl s_client 查到的 issuer 为 Let's Encrypt 中间证书、http 访问返回 301 跳转到 https。

一、为什么域名绑上了,浏览器还是提示“不安全”?

因为 *.github.io 的证书是 GitHub 自己的通配符证书,它只覆盖 username.github.io 这类子域,跟你绑定的 example.com 没有包含关系。在你完成绑定后、GitHub 为该域名单独签发证书前,访问 https://example.com 时 TLS 握手拿到的仍然是 CN=*.github.io 这张证书,浏览器比对 SAN 列表失败,就会抛出 NET::ERR_CERT_COMMON_NAME_INVALID(Chrome/Edge)或“此连接不受信任 / 证书名称不匹配”(Firefox)。注意此时 http://example.com 往往能正常打开——这恰好说明 DNS 已经生效,缺的只是证书,不要把问题误判成解析没做对。

用 OpenSSL 看一眼对端到底发了什么证书,比猜快得多(OpenSSL 1.1.1 / 3.x 通用,-servername 必须带,否则拿到的是默认虚拟主机证书):

# 查看当前 example.com 实际下发的证书主体、签发者与有效期
openssl s_client -connect example.com:443 -servername example.com /dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

# 未签发完成时的典型输出(说明还在用 GitHub 的默认证书)
# subject=CN = *.github.io
# issuer=C = US, O = Let's Encrypt, CN = R11
# notAfter=...            <-- 90 天有效期,跟你无关,是 GitHub 自己的
# X509v3 Subject Alternative Name: DNS:*.github.io, DNS:github.io

证书完全由 GitHub 托管:类型是 Let’s Encrypt 的 DV(域名验证)证书,有效期 90 天,GitHub 在到期前约 30 天自动续期,站长不需要也不应该在服务器上跑 certbot。据 GitHub Docs《Securing your GitHub Pages site with HTTPS》,这个流程有两项硬限制:不支持上传自有证书(BYOC,bring your own certificate),也不签发 *.example.com 通配符证书——所以 a.example.com 和 b.example.com 必须各自作为独立的自定义域名配置。

签发是异步排队的:GitHub 先探测 DNS 是否已正确指向 Pages(4 条 A 记录 185.199.108.153 / .109.153 / .110.153 / .111.153,或 CNAME 指向 USERNAME.github.io),确认后才向 Let’s Encrypt 提交 ACME 订单。官方给的最长等待时间是 24 小时,实测多数域名在 15 分钟内完成。

“Enforce HTTPS”复选框变灰,是 GitHub 判定当前不具备签发条件,而不是 bug。按下面四类逐一排除,每类都有可验证的判据:

原因 验证方式 修复方向
DNS 未生效或记录类型不对(用了 AAAA、把 CNAME 指向了 IP) dig +short example.com A 应恰好返回 4 条 GitHub IP 改为 4 条 A 记录;www 用 CNAME 指向 USERNAME.github.io.
CAA 记录未放行 Let’s Encrypt dig +short example.com CAA 添加 0 issue "letsencrypt.org"
域名已被其他 GitHub 账号/仓库占用(报 CNAME already taken) Pages 设置页红字提示,或换账号试绑 在占用方解除绑定,或先做域名归属验证
仓库里的 CNAME 文件内容与 Settings 中填写的域名不一致 cat CNAME 对比设置页 统一为不带协议、不带路径的裸域名 example.com

CAA 这一条最容易被忽略,也最值得单独查一次:

# 查 CAA:返回空表示没有限制(Let's Encrypt 可正常签发)
dig +short example.com CAA
# 若已有记录,必须包含下面这一条,否则 ACME 校验会被 CA 拒绝
# example.com. 300 IN CAA 0 issue "letsencrypt.org"
# 历史遗留建议同时保留 DigiCert 的授权,删记录前先确认当前签发 CA
# example.com. 300 IN CAA 0 issue "digicert.com"

补充一段容易被误传的历史:GitHub Pages 的自定义域名 HTTPS 于 2018 年上线,早期证书由 DigiCert 提供,之后才切换到 Let’s Encrypt。这正是很多老域名的 CAA 里同时写着 digicert.com 与 letsencrypt.org 的原因——在没确认当前签发 CA 之前,贸然删掉其中一条会让证书续期在 90 天后的某个夜里静默失败。另外,*.github.io 已进入浏览器 HSTS preload 列表,github.io 子域强制走 HTTPS;而你的自定义域名只有在勾选 Enforce HTTPS 之后才会得到 GitHub 侧的 301 跳转,两者不是一回事。想彻底跑通 github pages 自定义域名 ssl 的完整链路,顺序永远是:DNS 正确 → 等证书签发 → 再勾 Enforce HTTPS。

二、完整实操:8 步把自定义域名 HTTPS 跑通

这 8 步可以压缩成三个阶段:先在 GitHub 侧认领域名,再让 DNS 真正指过去,最后等 Let’s Encrypt 签发证书。顺序不能颠倒——DNS 没生效就点 Enforce HTTPS,只会让复选框一直灰着。下面每一步都给可直接复制的命令。

步骤 1–2:Custom domain 怎么填?CNAME 文件长什么样?

进入仓库 Settings → Pages → Custom domain,只填 example.com:不能带 https://、不能带结尾斜杠、不能带路径。点 Save 后,GitHub 会在仓库根目录自动提交一个 CNAME 文件(如果你用 GitHub Actions 部署,记得把它放进构建产物的根目录,否则每次发布都会被覆盖掉)。

# 仓库根目录 CNAME(由 Pages 设置页自动生成,内容仅一行)
# 不要加协议、不要加斜杠;文件末尾保留一个换行符
example.com

步骤 2–3:DNS 到底要加几条记录?

; 通用 zone 语法示例,控制台按同样语义逐条填写
; TTL 先设 300–600 秒,方便出错时快速回滚(默认常见值 3600 太长)
example.com.      300  IN  A      185.199.108.153      ; GitHub Pages 官方 A 记录,4 条缺一不可
example.com.      300  IN  A      185.199.109.153
example.com.      300  IN  A      185.199.110.153
example.com.      300  IN  A      185.199.111.153
example.com.      300  IN  AAAA   2606:50c0:8000::153  ; 可选:官方 IPv6 记录,建议一并配置
example.com.      300  IN  AAAA   2606:50c0:8001::153
example.com.      300  IN  AAAA   2606:50c0:8002::153
example.com.      300  IN  AAAA   2606:50c0:8003::153
www.example.com.  300  IN  CNAME  USERNAME.github.io.  ; 结尾的点别漏,部分服务商不补就报格式错误
解析方案 用于哪个主机名 记录值 优势 坑点
A 记录(推荐) apex:example.com 4 条 185.199.x.153 原生 DNS 语义,无展平兼容问题 少加一条会表现为间歇性 404 / 连接超时
CNAME(推荐) www.example.com USERNAME.github.io. GitHub 换 IP 时你无需改解析 apex 上不能放 CNAME(RFC 1034 禁止与 SOA/NS 共存)
ALIAS / ANAME apex USERNAME.github.io apex 也能跟随后端 IP 变化 仅 Cloudflare(CNAME Flattening)、DNSimple 等支持,不通用

apex 用 A、www 用 CNAME 后,GitHub 会自动做 301 归一化:访问 www.example.com 会跳到 example.com(以你在 Custom domain 里填的那个为准)。另外,据 GitHub 官方文档,如果用 Cloudflare 且开了橙色云朵(代理模式),HTTP-01 校验拿不到源站,证书会一直签不下来——签发阶段务必设为 DNS only。

步骤 4:怎么确认解析真的生效了?

# 期望输出 4 行 185.199.x.153
dig +short example.com A
# 期望先看到 USERNAME.github.io. 再跟出它的 A 记录
dig +short www.example.com
# 国内递归 DNS 受 TTL 与缓存影响,分别用两家公共 DNS 各验一次
dig @8.8.8.8   +short example.com A
dig @223.5.5.5 +short example.com A
# 查完整 CNAME 链,确认没有被 CDN 或旧记录劫持
dig +trace www.example.com

步骤 5:Enforce HTTPS 是灰的怎么办?

回到 Settings → Pages 勾选 Enforce HTTPS。默认它是关闭的;刚配好域名时通常灰 15–60 分钟,因为 GitHub 要先完成域名归属校验再向 Let’s Encrypt 申请证书。此时页面常提示 Domain's DNS record could not be retrieved. 或 Enforce HTTPS is unavailable for this domain.——先等,别急着反复删域名重加。据 Let’s Encrypt 官方限流文档,同一组域名每周最多签发 5 张重复证书,超过会返回 too many certificates already issued,反而被临时拒绝。证书本身有效期 90 天,GitHub 自动续期,无需你干预。

步骤 6–7:CAA 记录会不会把 Let’s Encrypt 挡在门外?

# 无任何输出 = 未配置 CAA,默认允许所有 CA 签发,最省事
dig CAA example.com +short
# 若已有输出,必须包含下面这一条,否则签发直接失败
# 0 issue "letsencrypt.org"
# 报错长这样:urn:ietf:params:acme:error:caa: CAA record for example.com prevents issuance
# 按 RFC 8659,CAA 沿域名逐级向上查找,所以 example.com 与 www.example.com 都要查
dig CAA www.example.com +short

如果 CAA 已放行、DNS 也正确,但超过 24 小时仍未签发,可删除 Custom domain 保存、等约 10 分钟再填回同一域名,这会触发 GitHub 重新排队申请。

步骤 8:能不能不点页面,直接用命令查状态并开强制 HTTPS?

# 需要 gh CLI ≥ 2.0(gh auth login 后使用)
# 查证书状态,期望 approved;中间态可能是 new / authorization_created / dns_changed
gh api repos/OWNER/REPO/pages --jq '.https_certificate.state'

# 直接用 API 开启强制 HTTPS,等价于勾选 Enforce HTTPS,省去在页面上等复选框变亮
gh api -X PUT repos/OWNER/REPO/pages -F https_enforced=true

# 一次性确认 cname、https_enforced 与证书状态
gh api repos/OWNER/REPO/pages 
  --jq '{cname: .cname, https_enforced: .https_enforced, state: .https_certificate.state}'

# 状态为 bad_authz / errored 说明 ACME 校验失败,回到步骤 4 与步骤 6 复查解析和 CAA

到这里 github pages 自定义域名 ssl 的链路就跑通了:https_certificate.state 返回 approved 且 https_enforced 为 true,浏览器地址栏出现锁标。若之后要迁到自有 CDN 或换用 Cloudflare 代理,记得回头复查 CAA 与 GitHub 的证书续期是否仍能通过 HTTP-01 校验——这是 github pages 自定义域名 ssl 最容易在半年后突然失效的地方。

三、配置与命令示例:DNS、CNAME 文件、API 与验证

DNS 到底要填几条记录才算”最小可用”?

GitHub Pages 的官方文档给出的 IPv4 是四条 A 记录,全部指向 apex 域(@);IPv6 是四条 AAAA。关键在于:IPv6 可以不加,但只要加就必须四条齐全——只填一两条会让部分走 IPv6 的客户端拿到不完整解析,表现为”手机能开、公司电脑打不开”这类诡异故障。

类型 主机记录 值 是否必需
A @ 185.199.108.153 / 185.199.109.153 / 185.199.110.153 / 185.199.111.153 必需,四条全填
AAAA @ 2606:50c0:8000::153 / 2606:50c0:8001::153 / 2606:50c0:8002::153 / 2606:50c0:8003::153 可选,加了就四条全填
CNAME www USERNAME.github.io 必需(www 子域)
# 验证 apex 与 www 是否都指向 GitHub(应各返回 4 条 A / 4 条 AAAA)
dig +short example.com A
dig +short example.com AAAA
dig +short www.example.com CNAME   # 期望 USERNAME.github.io.

# 换个公共 DNS 复核,排除本地缓存干扰
dig @1.1.1.1 +short example.com A

CNAME 文件怎么写才不会把域名搞丢?

仓库根目录的 CNAME 文件必须是单行 example.com:不带 https://、不带 www、不带 BOM、结尾不要多余空行。用 Windows 记事本”UTF-8 带 BOM”保存是最常见的翻车点,GitHub 会把 BOM 当成域名字符的一部分。

# 正常输出应为:example.com$
# 若出现 M-oM-;M-? 前缀,说明带了 UTF-8 BOM,必须重写
cat -A CNAME

# 重新写入(printf 不带 BOM,且只保留一个换行)
printf 'example.comn' > CNAME

用 GitHub Actions 发布时有个隐蔽陷阱:actions/deploy-pages 只认 artifact 里的文件,如果构建产物没有 CNAME,每次部署后 Settings → Pages 里的 Custom domain 会被清空。解决办法是在打包步骤补一行 echo "example.com" > ./dist/CNAME,并保证它与 Settings 中保存的值完全一致。

能不能用命令行开启强制 HTTPS 并查证书状态?

# 开启强制 HTTPS(-f 传字符串,-F 传布尔/类型化字段)
gh api -X PUT repos/OWNER/REPO/pages 
  -f cname=example.com 
  -F https_enforced=true

# 查询证书状态:state 为 approved 表示已签发,domains 列出证书覆盖的所有域名
gh api repos/OWNER/REPO/pages 
  --jq '{cname,https_enforced,state:.https_certificate.state,domains:.https_certificate.domains}'

怎么确认证书真的覆盖了 www?

# 取出叶子证书的 subject / issuer / 有效期 / SAN
openssl s_client -connect example.com:443 -servername example.com /dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

期望 subject=CN = example.com,SAN 同时含 example.com 与 www.example.com,issuer 为 Let’s Encrypt 中间证书(2024 年 3 月起为 R10/R11,R3 已停用)。若 SAN 缺 www,多半是 DNS 里 www 的 CNAME 还没生效就去点了签发。

最后一轮验收:跳转、HSTS、协议版本

# 1) HTTP 必须 301 到 HTTPS
curl -sI http://example.com | head -n 3
# 期望:HTTP/1.1 301 Moved Permanently / Location: https://example.com/

# 2) HSTS 头(GitHub 固定为一年,单位秒)
curl -sI https://example.com | grep -i strict-transport-security
# 期望:strict-transport-security: max-age=31556952

# 3) HTTP/2 与 TLS 版本枚举
curl -sI --http2 https://example.com | head -1        # 期望 HTTP/2 200
nmap --script ssl-enum-ciphers -p 443 example.com     # 只应出现 TLS 1.2 / TLS 1.3

GitHub Pages 已关闭 TLS 1.0/1.1,所以老客户端(如 Android 4.x 自带浏览器、Java 7 的 HttpsURLConnection)会直接握手失败,报 sslv3 alert handshake failure——这不是证书没签好,而是协议被服务端拒绝。HSTS 的 max-age=31556952 对应 RFC 6797 定义的一年时长,浏览器在此期间会强制走 HTTPS,排错时若想回退到 HTTP 测试,记得先清理 HSTS 缓存(Chrome 的 chrome://net-internals/#hsts)。到这里,github pages 自定义域名 ssl 的链路就从 DNS 一路验证到了 TLS 层。

四、方案选型:GitHub 原生证书 vs Cloudflare vs 自建反代

一句话结论:纯静态站 + 域名只做展示,选 GitHub 原生证书,0 元 0 维护;需要 CDN、WAF 或自有 EV 证书,才在前面加一层 Cloudflare 或自建反代。三种方案的差异集中在「证书归谁签发、续期谁负责、能不能换证书」这三点上,据 Let’s Encrypt 官方文档,其 DV 证书有效期 90 天、推荐在剩余 30 天时续期,这也是 GitHub Pages 与 certbot 的共同节奏。

方案 证书来源与类型 费用(2025 年公开定价) 自动续期 支持自有证书 适用场景
GitHub Pages 原生 Let’s Encrypt DV,90 天 0 元 是,GitHub 托管 否 个人站、文档站、纯静态博客
Cloudflare 免费版代理 Cloudflare Universal SSL 0 元 是 否 需要 CDN、WAF、防 DDoS
Cloudflare Business 可上传自定义证书 200 美元/月起 部分手动 是 必须用 OV/EV 或固定证书链
Nginx 自建反代 + certbot Let’s Encrypt DV,90 天 服务器 30–100 元/月 是,systemd timer 是 需要 HSTS Preload、mTLS、精细 TLS 套件
Netlify / Vercel Let’s Encrypt DV 0 元起 是 付费版可 想脱离 GitHub 生态

Cloudflare 的典型坑:橙云会挡住 HTTP-01 校验。GitHub 通过 HTTP-01 验证域名控制权,橙云代理后请求落到 Cloudflare 边缘,GitHub 拿不到 /.well-known/acme-challenge/ 的响应,证书会卡在 pending。首次签发必须先切成灰云(仅 DNS),等状态变成 approved 再切回橙云。用 GitHub REST API 直接查状态,别靠页面刷新猜:

# 查看 GitHub Pages 证书签发状态(需已配置自定义域名)
# 适用:GitHub REST API 2022-11-28 版本;需 personal token(public_repo 权限即可)
curl -s -H "Accept: application/vnd.github+json" 
     -H "Authorization: Bearer $GITHUB_TOKEN" 
     https://api.github.com/repos/<owner>/<repo>/pages 
  | jq '.https_certificate'
# 期望:{"state":"approved","description":"Certificate is approved",...}
# 卡住时常见 state:new / authorization_pending / dns_changed
# dns_changed 表示 DNS 记录改过,需要重新触发签发(先删自定义域名再重填)

切回橙云后,浏览器看到的是 Cloudflare 边缘证书,而源站证书仍需保持有效——这就是 SSL/TLS 加密模式必须选 Full 或 Full (strict) 的原因:Flexible 会让 Cloudflare 用 HTTP 回源,造成重定向循环,并让 GitHub 侧的证书形同虚设。Full (strict) 会校验证书签名与有效期,GitHub Pages 的 Let’s Encrypt 证书满足条件,可放心开。

成本区间参考:Let’s Encrypt 0 元;商业 DV 约 100–500 元/年;OV 约 800–3000 元/年;Cloudflare Pro 20 美元/月、Business 200 美元/月起,自定义证书上传从 Business 档开始。另外注意 Universal SSL 免费版只覆盖 example.com 与 *.example.com 一层,a.b.example.com 这类二级子域需要 Advanced Certificate Manager(约 10 美元/月)。

不建议的做法:把 apex 域名用 CNAME 直接指向 github.io。据 RFC 1034/1912,CNAME 不能与 apex 上的 SOA/NS 共存,多数 DNS 商直接拒绝;需改用 ALIAS/ANAME 记录或 Cloudflare 的 CNAME Flattening。先自检再动手:

# apex 是否被错误地设成了 CNAME(正常应无输出)
dig +short example.com CNAME

# 正确的 apex 应为 GitHub Pages 的 4 个 A 记录之一
dig +short example.com A
# 185.199.108.153 / 185.199.109.153 / 185.199.110.153 / 185.199.111.153

# 确认链路上拿到的证书是谁签的(判断是否已被 Cloudflare 接管)
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -issuer -subject -dates

五、常见报错与排查路径(附真实报错文本)

为什么 dig 返回 NXDOMAIN,GitHub 就报 “Domain’s DNS record could not be retrieved”?

这条报错的意思是 GitHub 在保存 Custom domain 时发起了一次权威 DNS 查询,但没拿到可用记录。最常见的原因是 apex 域只配了 CNAME(RFC 1034 禁止 apex 使用 CNAME),或者 A 记录还指向旧主机、Cloudflare 代理 IP。按 GitHub 官方文档,apex 应配 4 条 A 记录:185.199.108.153、185.199.109.153、185.199.110.153、185.199.111.153,www 子域配 CNAME 指向 yourname.github.io.。

# 1) 解析层:应看到 185.199.x.153,而不是 NXDOMAIN / 旧 IP / CDN 地址
dig +short example.com A
# 期望输出(4 行中任意 1~4 行):
# 185.199.108.153
# 185.199.109.153
dig +short www.example.com CNAME
# 期望: yourname.github.io.

# 2) HTTP 层:确认已 301 到 https 且落到正确仓库
curl -I http://example.com

# 3) TLS 层:证书是否已签发、SAN 是否覆盖当前域名
openssl s_client -connect example.com:443 -servername example.com /dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

# 4) 平台层:https_certificate.state 取值 approved / pending / none
gh api repos/OWNER/REPO/pages --jq '.https_certificate'

# 5) CAA 层:CAA 会沿父域逐级回溯,两级都要查
dig +short example.com CAA
dig +short com CAA

据 Let’s Encrypt 文档,签发前会从 FQDN 一路向上查到根,任何一层存在不含 letsencrypt.org 的 issue 属性都会拒绝签发,返回 CAA record for example.com prevents issuance。补一条即可:example.com. CAA 0 issue "letsencrypt.org"。

“Certificate is not yet available” 与 “already taken” 怎么区分?

前者是证书排队中或域名不匹配——典型坑是 Settings 里填了 www.example.com,却只配了 apex 的 A 记录,GitHub 校验 SAN 时找不到对应记录。后者是域名所有权冲突,GitHub 返回 The custom domain example.com is already taken by another repository 或 CNAME already taken,需登录原账号在对应仓库 Settings → Pages 删除 Custom domain 释放;若原仓库已删,走账号 Settings → Pages → Add a domain 做 TXT 验证,再联系 GitHub Support 人工释放。

报错文本 根因 一条命令定位
Domain’s DNS record could not be retrieved DNS 未生效 / apex 用了 CNAME dig +short example.com A
The custom domain … is already taken 域名被其他仓库占用 dig +short example.com CNAME 看指向哪个 *.github.io
Certificate is not yet available 证书排队 / 域名与记录不匹配 gh api … --jq .https_certificate
CAA record … prevents issuance CAA 白名单缺失 dig +short example.com CAA

页面样式全丢、控制台刷 Mixed Content 怎么办?

Mixed Content: The page at ‘https://example.com/’ was loaded over HTTPS, but requested an insecure resource ‘http://…’

把硬编码的 http:// 改成 https:// 或协议相对 //;无法逐个改时,在 <head> 加兜底:<meta http-equiv="Content-Security-Policy" content="upgrade-insecure-requests">。注意该指令只对同源子资源生效,跨域 CDN 仍需对方支持 HTTPS。

整个排查顺序固定为 dig → curl -I → openssl s_client → gh api → dig CAA,逐层收窄,绝大多数 github pages 自定义域名 ssl 签发问题可在 5 分钟内定位到具体一层。

六、效果验证:4 条命令确认 HTTPS 真的生效

证书状态变成 “Certificate issued” 只说明 ACME 流程走完了,不代表用户浏览器真的走了 HTTPS。下面 4 条命令从不同层面验证:HTTP 响应头、TLS 握手与证书有效期、浏览器安全上下文、双域名归一化,最后再给一份可直接挂到 cron 的巡检脚本。

第 1 条:curl -sI 看 HSTS 头在不在

# -I 只取响应头;-s 静默进度条。重点看状态码和 strict-transport-security
curl -sI https://example.com | head -20

# 期望输出(节选):
# HTTP/2 200
# strict-transport-security: max-age=31556952
# server: GitHub.com

返回 200 且带 strict-transport-security: max-age=31556952(即 1 年,GitHub Pages 的固定值),说明仓库 Settings → Pages 里的 Enforce HTTPS 已勾选。据 RFC 6797 对 HSTS 的定义,浏览器收到该头后,在 max-age 秒内对该域名强制使用 HTTPS,包括用户手敲 http:// 的场景。缺这个头几乎都是 Enforce HTTPS 没勾上,或勾选后证书尚未签发完成(GitHub 只有在证书就绪后才允许勾选)。

第 2 条:openssl s_client 看证书到期时间

# -servername 必须带上,否则 SNI 缺失会拿到默认证书(GitHub 会返回不匹配的证书)
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null 
  | openssl x509 -noout -dates -subject -ext subjectAltName

# 期望输出:
# notBefore=Jan 10 00:00:00 2025 GMT
# notAfter=Apr 10 00:00:00 2025 GMT
# subject=CN = example.com
# X509v3 Subject Alternative Name: DNS:example.com, DNS:www.example.com

GitHub Pages 通过 ACME 自动签发 Let’s Encrypt 证书,据 Let’s Encrypt 官方文档,证书有效期 90 天,官方建议在剩余 30 天时开始续期。所以 notAfter 距当前 60–90 天属正常;若只剩 10–20 天且日期不再前移,说明自动续期失败了,此时要检查两件事:域名是否配了指向其他 CA 的 CAA 记录(例如只允许 digicert.com),以及续期窗口内是否有人改过 DNS 的 A/CNAME 记录导致 HTTP-01 校验失败。

第 3 条:浏览器 DevTools 与 SSL Labs 交叉验证

打开 DevTools → Security 面板,应显示 “This page is secure (valid HTTPS).”;若出现 “mixed content” 警告,说明页面里还有 http:// 硬编码的图片或脚本,HSTS 不会帮你兜底。再跑一次 Qualys SSL Labs 的在线测试,GitHub Pages 站点通常拿到 A 评级(受限于平台侧统一配置,个别站点因自定义 CDN 会降到 A-)。

第 4 条:双域名归一化与 SAN 覆盖

# 看 www 是否 301 到裸域(或反向),并确认 Location 是 https
curl -sI https://www.example.com | head -3
# 期望:
# HTTP/2 301
# location: https://example.com/

# 再确认 www 的证书 SAN 里确实包含 www 子域,排除名称不匹配
echo | openssl s_client -connect www.example.com:443 -servername www.example.com 2>/dev/null 
  | openssl x509 -noout -ext subjectAltName

若 Location 指向 http://,说明 CNAME 文件里写的是绝对地址且漏了协议,或用了 jekyll-redirect-from 之类的插件生成了 http 跳转。回到 DNS 层面,两个主机名都要有指向 <username>.github.io 的 CNAME,GitHub 才会为两个名字都签发进同一张证书的 SAN,这是 github pages 自定义域名 ssl 配置里最容易被漏掉的一环。

对照表:4 条命令的判读标准

检查项 命令关键片段 正常输出 异常含义
强制 HTTPS / HSTS curl -sI https://域名 200 + strict-transport-security: max-age=31556952 缺 HSTS 头 → Enforce HTTPS 未勾选
证书有效期 openssl x509 -noout -dates notAfter 距今 60–90 天 剩余 <20 天 → 检查 CAA / DNS 是否阻断续期
浏览器安全上下文 DevTools → Security “valid HTTPS”,无混合内容 混合内容警告 → 页面内仍有 http 资源
域名归一化 curl -sI https://www.域名 301 + Location 指向 https 裸域 200 或 302 → CNAME 跳转未生效

进阶:把验证写成每天自动跑的巡检脚本

#!/usr/bin/env bash
# /usr/local/bin/check-gh-pages-tls.sh
# 依赖:openssl、curl、GNU date(macOS 需改用 date -j -f)
DOMAIN="example.com"
WARN_DAYS=20
ALERT="you@example.com"

# 1) 证书剩余天数,低于阈值告警
END=$(echo | openssl s_client -connect "$DOMAIN:443" -servername "$DOMAIN" 2>/dev/null 
      | openssl x509 -noout -enddate | cut -d= -f2)
LEFT=$(( ( $(date -d "$END" +%s) - $(date +%s) ) / 86400 ))
[ "$LEFT" -lt "$WARN_DAYS" ] && 
  echo "WARN $DOMAIN 证书仅剩 ${LEFT} 天,notAfter=$END" | mail -s "TLS 告警" "$ALERT"

# 2) http → https 跳转是否仍是 301,防止误改 DNS 后静默降级
CODE=$(curl -s -o /dev/null -w '%{http_code}' "http://$DOMAIN")
[ "$CODE" != "301" ] && 
  echo "WARN $DOMAIN 的 HTTP 跳转码变为 $CODE(期望 301)" | mail -s "跳转异常" "$ALERT"

挂到 crontab,每天 03:00 跑一次并把日志留档:

# crontab -e
0 3 * * * /usr/local/bin/check-gh-pages-tls.sh >> /var/log/gh-pages-tls.log 2>&1

这条脚本同时覆盖两个失效模式:证书静默过期,以及有人把 DNS 从 GitHub 指回旧主机后 HTTPS 被降级成 HTTP。对 github pages 自定义域名 ssl 的长期可靠性来说,后者比前者更隐蔽——因为浏览器不会报错,只是悄悄用了明文。

七、上线后的长期运维:续期、HSTS 与域名防接管

GitHub Pages 的证书会自动续期吗?会不会哪天突然掉线?

会自动续期,但“自动”不等于“必然”。据 GitHub Docs 的说明,自定义域名的证书由 Let’s Encrypt 签发,GitHub 会在证书到期前约 30 天自动重新签发,你不需要上传 CSR,也不需要运行 certbot。风险在于:ACME 的 HTTP-01 校验要求公网能把域名解析到 GitHub Pages 的 IP,任何一环断开,续期都会静默失败。GitHub 不会给你发失败邮件,只有等证书真的过期、浏览器弹出 NET::ERR_CERT_DATE_INVALID 时你才会发现。所以运维的重点不是“怎么续”,而是“怎么保证续期路径一直通畅”。

第一件必须长期保留的记录是 CAA。据 RFC 8659,CA 在签发前会查询 CAA;如果存在 CAA 但其中没有 issue "letsencrypt.org",Let’s Encrypt 会直接拒绝签发。更换 DNS 服务商时,CAA 记录最容易在迁移模板中被遗漏:

; DNS 区域文件片段(适用于 Cloudflare / Route 53 / 阿里云等任意服务商)
; 关键行:只授权 Let's Encrypt,避免 CAA 缺失导致续期被拒
example.com.   300 IN CAA 0 issue "letsencrypt.org"
example.com.   300 IN CAA 0 iodef "mailto:ops@example.com"

把下面四条命令保存成脚本,每月运行一次即可覆盖 90% 的续期隐患:

# 1) 确认 CAA 放行 Let's Encrypt(返回空 = 无 CAA,不阻断;返回其他 CA = 阻断)
dig +short CAA example.com

# 2) 确认 GitHub 域名校验 TXT 仍在(防域名接管)
dig +short TXT _github-pages-challenge-USERNAME.example.com

# 3) 读取线上证书的实际到期时间,与变更台账比对
openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -subject -dates

# 4) 确认 GitHub 下发的 HSTS 头(值固定,用户不可修改)
curl -sI https://example.com | grep -i strict-transport-security
# 期望输出:strict-transport-security: max-age=31556952
现象 首查命令 典型根因
到期日临近仍显示旧证书 dig +short CAA example.com CAA 只写了其他 CA,未含 letsencrypt.org
证书已过期,页面报 ERR_CERT_DATE_INVALID dig +short A example.com 切换 NS 后解析为空,HTTP-01 校验失败
无法在仓库中绑定该域名 dig +short TXT _github-pages-challenge-USERNAME.example.com 域名已被其他账号验证占用

HSTS 开了之后还能退回 HTTP 吗?不能,而且 GitHub 不给你调。GitHub Pages 固定下发 max-age=31556952(约 1 年),按 RFC 6797 的定义,浏览器会在这段时间内强制使用 HTTPS。这意味着:换域名后,老访客访问旧域名如果解析失败,就会看到不可跳过的证书错误;即使你后来取消自定义域名,回退到 USERNAME.github.io,旧域名的访客照样被 HSTS 强制走 HTTPS。唯一可行的做法是让旧域名长期保留并 301 到新域名,直到用户侧缓存自然过期。

怎么防止域名被别人绑到他的仓库?GitHub Pages 的域名归属靠一条 TXT 记录证明。在仓库 Settings → Pages → Add a domain 里填入域名后,按提示添加 _github-pages-challenge-USERNAME.example.com 的 TXT 值并点击验证;验证通过后,该域名即锁定到你的账号,其他账号无法再绑定。注意 USERNAME 要换成 GitHub 用户名的小写形式,且这条 TXT 在验证成功后不要删除。

换 DNS 服务商怎么才能不断证书?先把新服务商的全部 A、AAAA、CNAME 记录配好,把 TTL 降到 300 秒并观察 24 小时,确认 dig 结果与旧商一致后再切换 NS。若在证书续期窗口(到期前 30 天内)出现解析空窗,Let’s Encrypt 会校验失败;据 Let’s Encrypt 文档,同一组域名的 Duplicate Certificate 限制为每周 5 张,反复手动触发重签很容易触顶,导致一整天都签不出新证书。

最后建议建一份变更台账,字段至少包括:域名、DNS 服务商、当前 TTL、最近一次证书签发时间、证书 expires_at、CAA 与 TXT 记录值。这样出问题时可以直接比对“上次改了什么”,也能在申请人工支持时,快速说明是否已经触发过 Let’s Encrypt 的频率限制。

不需要。GitHub 会为该域名免费申请 Let's Encrypt DV 证书,有效期 90 天并自动续期,你只需在 Settings → Pages 勾选 Enforce HTTPS。只有需要 OV/EV 证书或通配符证书时,才需要自购并前置 Cloudflare 或自建反代。

说明 GitHub 判定当前不满足签发条件。按顺序查三件事:dig +short 域名是否返回 185.199.108.153~111.153、dig CAA 是否放行 letsencrypt.org、域名是否已被别的仓库绑定。DNS 改完后通常 15–60 分钟复选框变为可点,超过 24 小时可删除域名重新添加触发重试。

不能。GitHub Pages 只提供托管式 Let's Encrypt 证书,不支持自带证书(BYOC),也不签发 *.example.com 通配符。需要自有证书时,常见做法是前置 Cloudflare(Business 档起可上传)或自建 Nginx 反代 + certbot。

只托管静态页面、追求零维护,用 GitHub 原生,0 元且不用管续期。需要 CDN、WAF、防 DDoS 或国内访问优化,就在前面加 Cloudflare 免费版,SSL/TLS 模式选 Full (strict),不要选 Flexible,否则会出现 ERR_TOO_MANY_REDIRECTS 重定向循环。

多数 15 分钟内完成,GitHub 文档给出的上限是 24 小时。超时后先确认 DNS 与 CAA 无误,再删除 Custom domain 保存、等 10 分钟重新填入。注意 Let's Encrypt 对同一组域名有每周 5 张重复证书的限制,不要连续重试。

表示该域名已被另一个 GitHub 账号或仓库绑定。用原账号进入对应仓库 Settings → Pages 删除 Custom domain 即可释放;若找不到原仓库,在账号 Settings → Pages → Add a domain 用 TXT 记录完成域名验证后联系 GitHub Support 处理。

典型的混合内容问题,页面里仍引用 http:// 的资源会被浏览器拦截。把资源地址改成 https:// 或协议相对 //,Jekyll 站点可在 _config.yml 把 url 设为 https://example.com,必要时加 CSP 的 upgrade-insecure-requests 指令兜底。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。