微信小程序报证书链不完整怎么办?Android 真机 SSL 握手失败的排查与修复步骤
微信小程序报「证书链不完整」,本质是服务端 443 端口只下发了站点证书、没下发中间证书:用 openssl s_client -showcerts 统计 BEGIN CERTIFICATE 只有 1 张(正常应为 2 张),Android 的 Conscrypt/BoringSSL 不做 AIA 抓取,于是握手直接失败,而 iOS 会按 RFC 5280 的 AIA 扩展自动拉取中间证书并缓存,所以表现为「iOS 正常、Android 真机失败」。 最快修复:cat 站点证书.crt 中间证书.crt > fullchain.pem,把 Nginx 的 ssl_certificate 指向 fullchain.pem,nginx -t 通过后 systemctl reload nginx,秒级生效,成本 0 元。 判定命令:openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null | grep -c "BEGIN CERTIFICATE",返回 1 即证书链不完整,返回 2 为正常,返回 3 为带交叉签名根。 证书顺序不能错:叶子证书在前、中间证书在后,根证书不要放进 fullchain,否则握手包变大且部分客户端会告警;Let's Encrypt 自 2024 年起默认中间证书为 R10/R11(RSA)或 E5/E6(ECDSA)。 验证标准:openssl s_client 加 -verify 5 -verify_return_error 输出 Verify return code: 0 (ok),且 SSL Labs 的 Chain issues 不再显示 Incomplete,再用 Android 7.0/13 与 iOS 16 三台真机各跑一次 wx.request。
微信小程序报「证书链不完整」是什么现象?为什么 iOS 正常、Android 真机握手失败
最典型的现象是”同一个接口,三种环境三种结果”:在微信开发者工具 1.06.x 里勾选「不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」时,wx.request 全部 success;一旦取消勾选,或在 Android 真机(微信 8.0.x)上测试,fail 回调立刻返回 errMsg: "request:fail ssl hand shake error"(注意微信把它拼成了三个单词);而同一接口在 iOS 16 真机上稳定返回 statusCode: 200。这不是”偶发网络抖动”,而是同一条证书链在不同信任库上被校验出了不同结论。
先花 10 秒确认服务端到底下发了几张证书。据 OpenSSL 文档,s_client -showcerts 会打印服务端在 TLS 握手中发送的全部证书:
# 统计服务端下发的证书张数:1 张 = 只有叶子证书,链不完整
echo | openssl s_client -connect api.example.com:443
-servername api.example.com -showcerts 2>/dev/null
| grep -c "BEGIN CERTIFICATE"
# 更直观:看每张证书的 Subject / Issuer,确认是否缺中间证书
echo | openssl s_client -connect api.example.com:443
-servername api.example.com -showcerts 2>/dev/null
| openssl crl2pkcs7 -nocrl -certfile /dev/stdin
| openssl pkcs7 -print_certs -noout
# 用系统根库做一次完整路径校验(-verify_return_error 让校验失败直接报错)
openssl s_client -connect api.example.com:443 -servername api.example.com
-CAfile /etc/ssl/certs/ca-certificates.crt -verify_return_error </dev/null
# 期望输出:Verify return code: 0 (ok)
# 缺中间证书时常见:Verify return code: 20 (unable to get local issuer certificate)
条数为 1 即证书链不完整;正常应为 2 张(叶子 + 中间证书);使用交叉签名(cross-signed)过渡的场景为 3 张。返回码 20 是”本地找不到签发者”,返回码 21 是”无法验证第一张证书”,两者都指向中间证书缺失而非证书本身无效。
为什么 Android 挂、iOS 不挂?据 RFC 5280 §4.2.2.1,证书的 AIA(Authority Information Access)扩展可携带 caIssuers 地址,指向签发者证书的下载 URL。iOS 与 Windows 的证书链引擎会主动通过 HTTP 去拉取缺失的中间证书并缓存,所以”服务端少发一张”它们能自愈。Android 的 Conscrypt/BoringSSL 默认不做 AIA chasing,也不跨进程缓存中间证书,缺一张就直接抛 javax.net.ssl.SSLHandshakeException: Trust anchor for certification path not found。这就是”部分机型好、部分机型坏”的机制来源。
微信侧的硬性约束:request 合法域名必须是 HTTPS;基础库 2.x 起要求 TLS ≥ 1.2;证书须由系统根信任库中的 CA 签发,不接受自签证书,也不接受用户手动安装的 CA(Android 7.0 / API 24 起应用默认不信任用户 CA)。这意味着”让测试同学装个根证书”在真机上是无效方案。
| 现象 / errMsg | 根因 | 验证命令 |
|---|---|---|
request:fail ssl hand shake error,部分 Android 挂、iOS 正常 |
证书链不完整(缺中间证书) | s_client -showcerts 计数 = 1 |
certificate has expired |
证书过期,全机型一致失败 | openssl x509 -noout -dates |
Hostname mismatch |
域名不在 SAN 中 | openssl x509 -noout -text | grep -A1 "Subject Alternative Name" |
unsupported protocol / 握手失败 |
TLS 版本低于 1.2 | s_client -tls1_1 可复现、-tls1_2 通过 |
影响面常被低估。Android 在国内微信活跃用户中占比高,证书链不完整时的失败率与系统版本、是否经过 CDN 节点强相关(不同 CDN 节点的证书下发配置可能不一致),因此常被误判为”服务端偶发 502″或”用户网络差”。据 Let’s Encrypt 文档,其签发的中间证书为 ISRG Root X1/X2 下的交叉签名链,部署时务必在 Nginx 的 ssl_certificate 中把叶子证书与中间证书按”叶子在前、中间在后”拼接成 fullchain,而不是只填站点证书——这是下一节要展开的修复动作。
定位微信小程序证书链不完整的 6 个步骤(含 openssl 与 curl 命令)
先把结论说清楚:微信小程序报“证书链不完整”时,最先报错的通常是 Android 真机,而不是 iOS。原因是 Android 7.0(API 24)起,系统只信任 system 证书库中的根证书,并且会拒绝任何无法追溯回根证书的证书链;而 iOS 与桌面浏览器常常因为缓存或 AIA 补全而“看起来正常”。据 Android 官方 Network security configuration 文档,从 7.0 起,应用默认不再信任用户安装的 CA,这条规则直接决定了下面 6 步的排查顺序。微信小程序侧的典型报错是 request:fail ssl handshake aborted 或 errCode: -1;这些信息不足以定位问题,必须回到命令行逐层验证。
- 数证书张数:先判断服务端到底发了几张证书。
# 关键:-servername 触发 SNI(RFC 6066),缺失时多域名共用 IP 会取到默认站点证书 openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null | grep -c "BEGIN CERTIFICATE"输出
1表示只下发了叶子证书,属于证书链不完整;2表示叶子证书加中间证书,正常;3表示额外带交叉签名根,兼容老旧设备,可保留。 - 看层级是否首尾相接:定位断在哪一张。
# 按服务端下发顺序拆成 cert1.pem(叶子)、cert2.pem(中间)… openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null | awk '/BEGIN CERT/{n++} n{print > ("cert" n ".pem")}' for f in cert*.pem; do echo "== $f"; openssl x509 -in "$f" -noout -subject -issuer; done正常必须满足「叶子.i = 中间.s、中间.i = 根.s」。哪一张的
i:与上一张的s:对不上,断链就在那里。 - 本地校验:用 OpenSSL 复现错误码。
# -untrusted 传入中间证书,-CAfile 用系统根库 openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted cert2.pem cert1.pem # 期望输出:cert1.pem: OK据 OpenSSL 文档,
error 20 at 0 depth lookup: unable to get local issuer certificate表示缺中间证书;error 21 unable to verify the first certificate多因cert1.pem中混入了多余证书,或顺序颠倒。 - 看服务端配置指向。Nginx 最常见的错误是
ssl_certificate指向了只含叶子证书的cert.pem,而不是 certbot 生成的fullchain.pem(据 Let’s Encrypt 文档,fullchain = 叶子 + 中间)。Apache 2.4.8+ 起SSLCertificateFile本身就允许包含中间证书,SSLCertificateChainFile已废弃。Tomcat 9.0.x 用 JKS 时执行keytool -list -v -keystore api.jks | grep -i "Certificate chain length",输出1即为单证书、链不完整。# Nginx:顺序不可颠倒,叶子在前、中间在后 ssl_certificate /etc/nginx/ssl/api.example.com.fullchain.pem; ssl_certificate_key /etc/nginx/ssl/api.example.com.key; # Apache 2.4.8+ # SSLCertificateFile /etc/httpd/ssl/api.example.com.fullchain.pem - 在线复核。SSL Labs(Qualys)结果页的 Chain issues 若显示
Incomplete,会直接列出缺失中间证书的 CN 与下载链接;国内可用 myssl.com 的“证书链”检测交叉验证,把缺的那张与叶子证书按顺序拼接即可。 - 真机复现。微信开发者工具 → 真机调试,至少在 Android 7.0、Android 13、iOS 16 三档各测一次;同时在服务器侧执行
curl -vI https://api.example.com(curl 7.81.0 / Ubuntu 22.04),链不完整时典型输出为curl: (60) SSL certificate problem: unable to get local issuer certificate。注意 curl 可能因 OpenSSL 的 AIA 自动补链而“假通过”,所以最终判定以 Android 真机为准。
| 检测命令 / 来源 | 结果 | 含义 | 处理动作 |
|---|---|---|---|
grep -c "BEGIN CERTIFICATE" |
1 | 仅叶子证书,链不完整 | 合并 fullchain 并重载服务 |
| 同上 | 2 | 叶子 + 中间,标准链 | 无需处理 |
| 同上 | 3 | 含交叉签名根 | 保留,兼容老设备 |
openssl verify |
error 20 | 缺中间证书 | 补中间证书 |
openssl verify |
error 21 | 顺序错或多证书混装 | 拆分后按叶子→中间重排 |
keytool -list -v |
chain length: 1 | JKS 内只有叶子 | 用 keytool -importcert 补链后重启 Tomcat |
修复后的验收标准很明确:重跑步骤 1 应输出 2 或 3,SSL Labs 的 Chain issues 不再出现 Incomplete,且 Android 7.0 真机上微信小程序不再出现握手失败。若仍失败,问题就不在证书链,应转向 TLS 版本协商(RFC 8446 的 1.3 与部分 Android WebView 的兼容)或 SNI 与 IP 直连的匹配问题继续排查。
Nginx、Apache、Tomcat、Spring Boot 补全证书链的配置示例与参数
把证书链补全,本质是让服务器在 TLS 握手时把「叶子证书 + 中间证书」一起发给客户端。微信小程序运行在 Android WebView / X5 内核里,它不会像桌面浏览器那样自动去下载缺失的中间证书,所以只要服务器只发叶子证书,就会直接抛出 net::ERR_CERT_AUTHORITY_INVALID 或握手失败。第一步永远是合并文件,顺序不能错:
# 叶子证书在前,中间证书在后;根证书绝对不要加入
cat api.example.com.crt intermediate.crt > api.example.com.fullchain.pem
# 校验张数:期望输出 2(叶子 + 中间);输出 3 说明混进了根证书
grep -c "BEGIN CERTIFICATE" api.example.com.fullchain.pem
# 验证链能否闭合(据 OpenSSL verify 手册,-untrusted 传入中间证书)
openssl verify -untrusted intermediate.crt api.example.com.crt
# api.example.com.crt: OK
根证书不放的理由很实际:它已经在 Android/iOS 系统信任库中,放进去只会让 ServerHello 之后的证书包多 1–2 KB,而部分老版本 Android(如 7.x 的部分 ROM)对链长度有硬限制,链过长反而报错。这也是 Let’s Encrypt 官方文档明确建议「fullchain 只含叶子与中间证书」的原因。
| 服务器 / 框架 | 承载证书链的文件 | 关键配置项 | 易错点 |
|---|---|---|---|
| Nginx 1.24 | fullchain.pem | ssl_certificate |
同文件内多张证书按序排列 |
| Apache 2.4.8+ | fullchain.pem | SSLCertificateFile |
SSLCertificateChainFile 已废弃 |
| Tomcat 9.0.x | JKS / PKCS12 | certificateKeystoreFile |
中间证书须导入同一 keystore |
| Spring Boot 3.2 | PEM | server.ssl.certificate |
只能填 fullchain,不能填叶子 |
Nginx 1.24:
server {
listen 443 ssl;
server_name api.example.com;
# 只写叶子证书 = 微信小程序端报证书链不完整
ssl_certificate /etc/nginx/ssl/api.example.com.fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/api.example.com.key;
ssl_protocols TLSv1.2 TLSv1.3; # 1.23+ 默认值即 TLSv1.2 TLSv1.3
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
ssl_session_cache shared:SSL:10m; # 默认 none
ssl_session_timeout 10m; # 默认 5m
}
顺带把 OCSP Stapling 打开,Android 端可少一次 OCSP 查询往返:
ssl_stapling on; # 默认 off
ssl_stapling_verify on; # 默认 off
# 只放「中间 + 根」,不含叶子证书,用于验证 OCSP 响应签名
ssl_trusted_certificate /etc/nginx/ssl/api.example.com.chain.pem;
resolver 223.5.5.5 119.29.29.29 valid=300s;
改完执行 nginx -t && systemctl reload nginx。Apache 2.4.8+ 同理,据 Apache 2.4 文档,SSLCertificateChainFile 自 2.4.8 起已标记废弃,因为 SSLCertificateFile 本身即可包含多张证书:
SSLCertificateFile /etc/httpd/ssl/api.example.com.fullchain.pem
SSLCertificateKeyFile /etc/httpd/ssl/api.example.com.key
# SSLCertificateChainFile 已废弃,不要再配置,否则可能与 fullchain 冲突
执行 apachectl configtest && systemctl reload httpd。Tomcat 9.0.x 走 keystore,中间证书必须显式导入:
# 方式一:导入同一个 JKS
keytool -importcert -alias intermediate -file intermediate.crt
-keystore api.jks -storepass changeit -noprompt
# 方式二:用 -certfile 把链一起打进 PKCS12
openssl pkcs12 -export -in api.example.com.fullchain.pem
-inkey api.example.com.key -out api.p12
-name api.example.com -passout pass:changeit
<SSLHostConfig>
<Certificate certificateKeystoreFile="conf/api.p12"
certificateKeystoreType="PKCS12"
certificateKeystorePassword="changeit" />
</SSLHostConfig>
Spring Boot 3.2 内嵌 Tomcat 支持直接读 PEM,但 server.ssl.certificate 指向的必须是 fullchain:
server.port=8443
# 若此处指向只有叶子证书的 .pem,Android 端同样报证书链不完整
server.ssl.certificate=classpath:ssl/fullchain.pem
server.ssl.certificate-private-key=classpath:ssl/privkey.pem
server.ssl.enabled-protocols=TLSv1.2,TLSv1.3
改完用一条命令确认线上实际发出的张数,返回 1 就说明修复没生效:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts
</dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE"
# 期望输出:2
补全 fullchain、开 AIA、换云托管、换 CA:四种修复方案怎么选
问:证书链不完整,先动哪一刀最省事?
方案 A(补全 fullchain)是首选:改一次配置 + reload,秒级生效、零成本,且不依赖任何客户端特性。只要故障根因是「服务端没下发中间证书」,方案 A 一定能修好。典型证据是 Android 真机抛出 Trust anchor for certification path not found,而 openssl s_client 只回一张证书。
# 1) 拼接顺序必须是「站点证书 → 中间证书」,顺序写反同样握手失败
cat your_domain.crt intermediate.crt > fullchain.pem
# 2) 本地校验,期望输出 "fullchain.pem: OK";报 unable to get local issuer certificate 说明漏了中间证书
openssl verify -untrusted intermediate.crt fullchain.pem
# 3) Nginx(全版本通用写法:指向含中间证书的 fullchain,而不是 cert.pem)
# ssl_certificate /etc/nginx/ssl/fullchain.pem; # 站点证书 + 中间证书
# ssl_certificate_key /etc/nginx/ssl/privkey.key;
nginx -t && nginx -s reload
# 4) 线上复核:统计服务端实际下发的证书张数,应为 2 张及以上
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null
| grep -c "BEGIN CERTIFICATE"
Apache 2.4.8 起 SSLCertificateChainFile 已废弃,直接 SSLCertificateFile 指向 fullchain 即可;Tomcat 则需把「站点证书 + 中间证书」按序导入同一个 PKCS12。最常见的坑是:certbot 生成的 fullchain.pem 本来就有中间证书,配置却只写了 cert.pem;以及续期脚本把 fullchain.pem 覆盖回单证书。
| 方案 | 改动位置 | 生效时间 | 成本区间 | 适用场景 | 主要风险 |
|---|---|---|---|---|---|
| A 补全 fullchain | Nginx/Apache/Tomcat 配置 | reload 后秒级 | 0 元 | 自有服务器,90% 以上场景 | 顺序写错、续期被覆盖 |
| B 依赖 AIA 抓取 | 证书本身带 caIssuers | 立即 | 0 元 | 仅作兜底 | Android 不支持,等于无效 |
| C 云托管证书 | CLB/CDN/SLB 控制台 | 1–5 分钟 | 0–500 元/年 | 无服务器权限、多域名 | 「证书链」字段留空 |
| D 更换 CA | 重新签发 | 10–30 分钟 | 0–3000 元/年 | 老 Android 占比高 | 需重做自动化续期 |
成本为 2024–2025 年常见区间,仅供参考。
问:证书里带了 AIA 扩展,客户端不能自己补链吗?
不能指望。据 RFC 5280 第 4.2.2.1 节,Authority Information Access 的 id-ad-caIssuers 只是「可选」提示,是否去抓取完全取决于客户端实现。Android 的 Conscrypt/BoringSSL 在链验证时不做 AIA chasing,所以「证书带 caIssuers 就自动补全」在 Android 上不成立;它只能作为 iOS/macOS/Windows 的兜底。方案 B 永远不能单独使用。
问:服务器不归我管,只有控制台权限怎么办?
走方案 C。腾讯云 CLB/CDN、阿里云 SLB 上传证书时都分「证书」与「证书链」两个字段,由平台负责拼接。最常见的坑就是把「证书链」留空,效果与自建 Nginx 只配 cert.pem 完全一样,症状不变。上传后同样用上面第 4 条 s_client 数证书张数复核。
问:什么时候才值得换 CA?
看存量设备。选择中间证书被广泛预置、且提供交叉签名的 CA(如 Let’s Encrypt 的 ISRG Root X1、DigiCert Global Root G2),对 Android 7.1.1 以下老设备兼容性更好。注意两点:一是证书有效期仍受 CA/Browser Forum 规定的 398 天上限约束(Let’s Encrypt 默认 90 天),换 CA 不改变续期频率;二是续期自动化必须同步改造,否则 90 天后回到原点。
选型结论
- 优先 A:先确认服务端下发张数 ≥ 2,绝大多数「微信小程序 证书链不完整」在此收工。
- 其次 C:无服务器权限、或多域名/多地域分发时使用。
- B 只作补充,不作为修复手段。
- D 仅在存量老设备占比高、或原 CA 中间证书在部分国产 ROM 上缺失时考虑;切换前用 SSL Labs 与 Android 真机各验证一轮,确认
openssl s_client返回Verify return code: 0 (ok)。
微信小程序证书链不完整常见的 7 条真实报错与排查清单
先给结论:在 Android 真机上,微信小程序对证书链的容忍度比桌面浏览器低得多。桌面浏览器和部分客户端会缓存中间证书,或者自动补齐中间证书(AIA fetching),而 Android 系统的 TrustManager 和微信内置网络库只认「服务器下发的证书链 + 系统根证书库」,中间证书缺失时不会自行补齐。因此,微信小程序出现证书链不完整时,往往表现为「浏览器能打开、开发者工具能跑通、真机必挂」。
把下面 7 条报错当作排查入口,基本可以在 15 分钟内确认问题属于证书链、根证书过期还是配置错误:
| 报错原文(可直接搜索) | 出现位置 | 指向链不完整的概率 |
|---|---|---|
request:fail ssl hand shake error |
小程序真机,Android 占多数 | 高(需配合下方命令确认) |
net::ERR_CERT_AUTHORITY_INVALID / net::ERR_CERT_INVALID |
微信开发者工具控制台 | 高,基本可先按缺中间证书处理 |
javax.net.ssl.SSLHandshakeException: java.security.cert.CertPathValidatorException: Trust anchor for certification path not found. |
Android logcat / 原生 App | 确认级,缺中间证书的标准堆栈 |
curl: (60) SSL certificate problem: unable to get local issuer certificate |
curl 7.81+ 命令行 | 确认级 |
error 20 at 0 depth lookup: unable to get local issuer certificateerror 21 unable to verify the first certificate |
openssl verify(OpenSSL 1.1.1/3.x) |
确认级 |
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target |
Java 8/11/17 客户端 | 确认级 |
UNABLE_TO_VERIFY_LEAF_SIGNATURE(Node.js 20)/ certificate verify failed: unable to get local issuer certificate(Python requests) |
服务端调用、CI 脚本 | 确认级 |
有一个坑必须先排除:开发者工具里「详情 → 本地设置 → 不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」一旦勾选,证书错误就会被吞掉,只剩真机报 ssl hand shake error。据微信开放文档的网络章节,正式版小程序强制要求 HTTPS 且服务端 TLS 版本不低于 1.2,所以这条勾选项只能用来排除干扰,不能作为验收依据。
三步定位:到底少的是哪一张证书?(OpenSSL 1.1.1 及以上;macOS 自带 LibreSSL 不支持部分参数,建议用 brew install openssl@3)
# 1) 抓取服务端实际下发的证书链(-servername 模拟 SNI,多域名共用 IP 时必须带)
openssl s_client -connect api.example.com:443 -servername api.example.com
-showcerts </dev/null 2>/dev/null > chain.pem
# 2) 数张数 + 看 s:(主题) / i:(签发者) 是否首尾相接
# 正常为 2~3 张:叶子 + 中间CA(+ 可选交叉证书)
grep -c 'BEGIN CERTIFICATE' chain.pem
openssl crl2pkcs7 -nocrl -certfile chain.pem | openssl pkcs7 -print_certs -noout | grep -E 'subject|issuer'
# 3) 用系统根证书库做真实校验:Verify return code 必须是 0 (ok)
openssl s_client -connect api.example.com:443 -servername api.example.com
-verify_return_error </dev/null 2>/dev/null | grep -E 'Verify return code|verify error'
如果第 2 步的 i:(签发者)与下一张的 s:(主题)对不上,就是链断裂;如果只有 1 张证书,则是服务器根本没有下发中间证书——这是 Nginx 配了 cert.pem 而不是 fullchain.pem 的典型症状。
两个极易误判的「假证书链不完整」
- 根证书过期:据 Let’s Encrypt 官方公告,DST Root CA X3 于 2021-09-30 到期,Android 7.1.1 及更早系统(不信任 ISRG Root X1)访问旧交叉签名链会直接握手失败,现象与缺中间证书几乎一致。用逐张查看
notAfter区分:# 拆成单张证书并逐张打印有效期(配合上面的 chain.pem) awk '/BEGIN CERTIFICATE/{n++} {print > "cert"n".pem"}' chain.pem for f in cert*.pem; do echo "== $f"; openssl x509 -in "$f" -noout -subject -issuer -dates; done - 配置类问题:SNI 未生效时,多域名共用 IP 会返回默认站点证书,报的是
hostname mismatch(X509_check_host失败),不是链问题;ssl_protocols只留 TLSv1.0/1.1 会被微信直接拒绝(Nginx 1.23.4 起默认值已改为TLSv1.2 TLSv1.3,更早版本默认是TLSv1 TLSv1.1 TLSv1.2);服务器或手机系统时间偏差超过 10 分钟会报certificate is not yet valid/certificate has expired。
推荐排查顺序:数证书张数 → 核对 s:/i: 是否首尾相接 → openssl verify → 核对 Nginx/Apache 配置指向 → SSL Labs 复核(看 “Chain issues” 一栏是否标 Incomplete)→ Android 真机回归。对应的最小修复通常只是改一行:
# /etc/nginx/conf.d/api.conf —— Nginx 1.18+ 验证通过
ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem; # 必须 fullchain,不能是 cert.pem
ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3; # 微信小程序要求 ≥ TLS 1.2
ssl_trusted_certificate /etc/letsencrypt/live/api.example.com/chain.pem; # OCSP stapling 需要,可选
改完执行 nginx -t && nginx -s reload,再回到第 3 步确认 Verify return code: 0 (ok),最后用 Android 真机(建议覆盖 Android 7 与 Android 12 各一台)复测小程序接口。
改完怎么确认证书链不完整已修复?6 种可复现的验证方法
改完 Nginx 的 ssl_certificate 只代表文件换了,不代表链对了。最常见的假阳性是:openssl s_client 默认只打印验证结果、不阻断连接,看到 Verify return code: 0 (ok) 就以为通过——据 OpenSSL 文档,必须加 -verify_return_error,验证失败才会以非零退出码中止;而且不加 -showcerts 时只输出叶子证书,你根本数不到中间证书。所以下面 6 种方法要组合使用。
方法 1:openssl 严格校验,两个条件同时满足才算过
# -showcerts:打印服务器发送的全部证书(默认只有叶子证书,无法计数)
# -verify 5:允许最多 5 层中间证书(3 层常见链足够)
# -verify_return_error:验证失败立即中止并以非零码退出(关键,默认只告警不中止)
# -servername:显式发 SNI,避免取到默认站点的证书
openssl s_client -connect api.example.com:443 -servername api.example.com
-showcerts -verify 5 -verify_return_error </dev/null > /tmp/chain.txt 2>&1
echo "exit=$?"
# 条件一:链验证必须通过
grep -q "Verify return code: 0 (ok)" /tmp/chain.txt && echo "PASS-1"
# 条件二:证书张数 ≥ 2(叶子 + 至少一张中间证书)
test "$(grep -c 'BEGIN CERTIFICATE' /tmp/chain.txt)" -ge 2 && echo "PASS-2"
按 RFC 8446 §4.4.2(以及 TLS 1.2 的 RFC 5246 §7.4.2),certificate_list 中每张证书必须直接认证前一张,顺序为叶子在前、根证书可省略。少于 2 张就一定是链不完整。
方法 2:逐张看有效期,避免刚修完链又撞上过期
# 按 BEGIN CERTIFICATE 切分成 c1.pem、c2.pem…
awk '/BEGIN CERTIFICATE/{n++} n{print > ("/tmp/c" n ".pem")}' /tmp/chain.txt
for f in /tmp/c*.pem; do
echo "== $f"
openssl x509 -in "$f" -noout -subject -issuer -dates
# -checkend 2592000 = 30 天;返回非 0 表示 30 天内过期
openssl x509 -in "$f" -noout -checkend 2592000 || echo "!! 30 天内过期"
done
据 Let’s Encrypt 文档,其证书有效期 90 天、中间证书也会轮换,所以续期后务必重跑方法 1,确认新证书文件里仍然拼接了中间证书。
方法 3:在线复测(人工确认,不宜进流水线)
- SSL Labs:Certificate 一栏应显示 Chain of trust: Yes、证书张数为 2,且不再出现 Chain issues: Incomplete,目标评级 A 及以上。
- myssl.com 证书链检测:结果应显示「完整」。
方法 4:微信侧真机回归
开发者工具里取消勾选「不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」,然后在 Android 7.0、Android 13、iOS 16 三台真机各调用一次 wx.request,检查 success 回调里 res.statusCode === 200 且没有触发 fail。Android 必须覆盖,因为据 Android 官方文档,从 Android 7.0(API 24)起应用默认不再信任用户安装的 CA,系统信任库更严格,链不完整时典型报错是 SSLHandshakeException: Trust anchor for certification path not found。
方法 5:多信任库交叉验证
# OpenSSL 3.0 信任库
curl -vI https://api.example.com/ 2>&1 | grep -E "SSL certificate verify|subject:|issuer:"
# Node.js 20(内置 Mozilla CA),链不完整会抛 UNABLE_TO_VERIFY_LEAF_SIGNATURE
node -e "require('https').get('https://api.example.com/',r=>console.log(r.statusCode)).on('error',e=>console.error(e.code,e.message))"
// OkHttp 4.12.0:默认信任平台 CA 存储(Android 上即系统 CA,不含用户证书)
OkHttpClient c = new OkHttpClient();
try (Response r = c.newCall(new Request.Builder().url("https://api.example.com/").build()).execute()) {
System.out.println(r.code()); // 期望 200
}
方法 6:持续监控,防止续期后被覆盖回单证书
# blackbox_exporter v0.25.x 内置指标 probe_ssl_earliest_cert_expiry(Gauge,Unix 时间戳)
# Prometheus 告警规则:30/15/7 天三档
groups:
- name: tls-chain
rules:
- alert: TlsCertExpiring30d
expr: probe_ssl_earliest_cert_expiry{job="blackbox"} - time() < 30*24*3600
for: 10m
- alert: TlsCertExpiring7d
expr: probe_ssl_earliest_cert_expiry{job="blackbox"} - time() < 7*24*3600
for: 10m
# /etc/cron.d/tls-chain-check —— 每天 09:00 数一次证书张数,<2 直接告警
0 9 * * * root n=$(openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE"); [ "$n" -ge 2 ] || /usr/local/bin/alert.sh "chain_count=$n"
| 方法 | 验证层面 | 单次耗时 | 能发现的问题 | 可否进 CI |
|---|---|---|---|---|
| 1 openssl 严格校验 | 服务端实际下发内容 | 约 1 秒 | 缺中间证书、顺序错、根证书多余 | 可以,推荐 |
| 2 逐张看有效期 | 每张证书的时间窗口 | 约 2 秒 | 叶子或中间证书即将过期 | 可以 |
| 3 SSL Labs / myssl | 外部视角 + 评级 | 1~3 分钟 | Chain issues、协议与套件问题 | 不建议 |
| 4 微信真机回归 | 小程序运行时信任库 | 5~10 分钟 | Android 7.0+ 信任策略差异、域名不匹配 | 不可 |
| 5 多信任库 | curl / Java / Node 各自 CA | 约 3 秒 | 只修好单条链路、交叉证书缺失 | 可以 |
| 6 持续监控 | 时间维度回归 | 常驻 | 续期覆盖回单证书、静默过期 | 不适用 |
最后提醒一个易混淆点:OCSP stapling 与证书链完整性是两件事,ssl_stapling on 配置正确也不会让缺失中间证书的链通过校验;反之,链修好了但 ssl_trusted_certificate 没指向中间证书,stapling 仍会失败。修完微信小程序证书链不完整问题后,先跑方法 1 与方法 5,再上真机,最后把方法 6 落地,才算闭环。
如何避免续期后再次出现证书链不完整?自动化与上线检查清单
为什么证书续期成功了,微信小程序却又报”证书链不完整”?
大多数复发不是 ACME 客户端的问题,而是续期后 Nginx 读的证书文件里只有叶子证书。据 Let’s Encrypt 文档,ACME 签发的证书本身不含中间证书,中间证书必须由服务端在握手时一并下发。certbot 在 /etc/letsencrypt/live/api.example.com/ 下同时生成 cert.pem(仅叶子)和 fullchain.pem(叶子 + 中间证书),ssl_certificate 一旦指向 cert.pem,浏览器可能靠 AIA 补链”侥幸通过”,而 Android 微信 WebView 与小程序网络库不做 AIA 抓取,直接握手失败——这正是”续期后才复发”的头号原因。
# /etc/nginx/conf.d/api.conf —— 关键:指向 fullchain.pem,不是 cert.pem
server {
listen 443 ssl;
server_name api.example.com;
ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem; # 含中间证书
ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3; # 微信要求 TLS ≥ 1.2
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/letsencrypt/live/api.example.com/chain.pem; # OCSP 校验用
}
# certbot ≥ 2.0:续期成功后自动平滑重载(--deploy-hook 仅在真正续期时执行)
certbot renew --deploy-hook "systemctl reload nginx"
acme.sh 用户注意:默认产物是 fullchain.cer
# acme.sh 3.x —— 安装证书到 Nginx 目录并注册续期后重载命令
acme.sh --install-cert -d api.example.com
--key-file /etc/nginx/ssl/api.key
--fullchain-file /etc/nginx/ssl/api.fullchain.pem # 对应 fullchain.cer,含中间证书
--reloadcmd "systemctl reload nginx"
# 反例:用 --cert-file 会把 cert.cer(仅叶子)装进去,链就断了
| 对比项 | certbot ≥ 2.0 | acme.sh 3.x |
|---|---|---|
| 含中间证书的产物 | fullchain.pem |
fullchain.cer |
| 仅叶子证书(勿用于 ssl_certificate) | cert.pem |
cert.cer |
| 续期后触发动作 | --deploy-hook |
--reloadcmd(安装时注册,续期自动执行) |
| 默认密钥类型 | ECDSA P-256(2.0 起) | RSA 2048(--keylength ec-256 可改) |
如何在 deploy hook 里加一道”链不完整就不许 reload”的闸门?把下面的自检放进 hook 脚本:
#!/bin/sh
# /etc/letsencrypt/renewal-hooks/deploy/chain-check.sh (chmod +x)
COUNT=$(openssl s_client -connect 127.0.0.1:443 -servername api.example.com
-showcerts /dev/null | grep -c "BEGIN CERTIFICATE")
if [ "$COUNT" -lt 2 ]; then
logger -t ssl "证书链仅 ${COUNT} 张,已中止 reload"; exit 1
fi
systemctl reload nginx # 自检通过才平滑重载
hook 返回非零会让 certbot 以非零码退出,配合 systemd timer 的 OnFailure= 即可触发告警,避免残缺链被推上线。注意重载用 reload 而非 restart:Nginx reload 是平滑重载、不断开存量连接,restart 会瞬间拒绝新连接,小程序端可能直接抛出握手异常。
上线前必须全过的六项检查(建议写进发布单,缺一不发):
- 证书张数 ≥ 2:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE" - 剩余有效期 > 30 天:同上管道接
| openssl x509 -noout -enddate - TLS ≥ 1.2:
openssl s_client -connect api.example.com:443 -tls1_1必须失败 - SNI 正常:对纯 IP 加
-servername能返回预期域名证书 - OCSP Stapling 可解析:
-status输出OCSP Response Status: successful - Android 真机回归:微信开发者工具”真机调试”通过,不能只看模拟器
别只修主域名。在微信公众平台「开发管理 → 开发设置 → 服务器域名」里,request、socket、uploadFile、downloadFile 四类合法域名各自独立(每类上限 20 个),逐条跑上面第 1 项检测,避免”接口通了、上传失败”。变更安排在业务低峰期,旧证书文件用 cp -a 保留 7 天以便回滚;任何时候先 nginx -t 再 reload。
不是。免费 DV 证书(Let's Encrypt、部分云厂商免费 DV)同样可以让小程序正常请求,前提是服务端把中间证书一起下发。证书链不完整是部署问题,不是证书等级问题,先按 fullchain 方式补齐再判断是否需要换证书。
浏览器和 iOS 支持按 RFC 5280 的 AIA 扩展自动抓取中间证书并缓存,即使服务端只下发叶子证书也能补齐;Android 的 Conscrypt/BoringSSL 不做 AIA chasing,缺一张中间证书就握手失败。所以「浏览器正常」不能证明证书链完整。
一般不要。根证书已经在客户端系统信任库里,放进 fullchain 只会让握手包变大 1–2 KB,部分老客户端还可能因链过长报错。fullchain 的正确内容是「叶子证书 + 中间证书」,交叉签名场景最多再加一张中间证书。
自建 Nginx 需要自己 cat 出 fullchain.pem 并保证顺序;腾讯云 CLB/CDN、阿里云 SLB 是在控制台分别填「证书」和「证书链」两个字段,由平台拼接,最常见的坑是把「证书链」留空,效果等同于只配了 cert.pem。没有服务器权限时用云托管更省事,但要记得两个字段都填。
按顺序查四点:一是 fullchain 里证书顺序是否叶子在前;二是是否走了 CDN/WAF,回源证书被替换成单证书;三是是否开了 SNI,多域名共用 IP 时返回了默认站点证书;四是 openssl s_client 是否带 -servername。这四点覆盖了绝大多数「配了但没生效」的情况。
证书过期通常报 certificate has expired 或 net::ERR_CERT_DATE_INVALID,且所有客户端一起失败;证书链不完整报 unable to get local issuer certificate、Trust anchor for certification path not found,典型表现是 iOS 正常、Android 失败。用 openssl x509 -noout -dates 逐张看 notAfter 可以快速确认。
不必须。微信小程序要求 TLS ≥ 1.2,配置 TLSv1.2 与 TLSv1.3 同时开启即可,TLS 1.3 只影响握手性能,不影响证书链校验结果。真正会导致 hand shake error 的是把协议限制到 TLSv1.0/1.1,或者中间证书缺失。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。