跳到主要内容
安装配置教程

微信小程序报证书链不完整怎么办?Android 真机 SSL 握手失败的排查与修复步骤

微信小程序 证书链不完整 — 微信小程序报证书链不完整怎么办?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;这些信息不足以定位问题,必须回到命令行逐层验证。

  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 表示额外带交叉签名根,兼容老旧设备,可保留。

  2. 看层级是否首尾相接:定位断在哪一张。
    # 按服务端下发顺序拆成 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: 对不上,断链就在那里。

  3. 本地校验:用 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 中混入了多余证书,或顺序颠倒。

  4. 看服务端配置指向。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
  5. 在线复核。SSL Labs(Qualys)结果页的 Chain issues 若显示 Incomplete,会直接列出缺失中间证书的 CN 与下载链接;国内可用 myssl.com 的“证书链”检测交叉验证,把缺的那张与叶子证书按顺序拼接即可。
  6. 真机复现。微信开发者工具 → 真机调试,至少在 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 certificate
error 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 会瞬间拒绝新连接,小程序端可能直接抛出握手异常。

上线前必须全过的六项检查(建议写进发布单,缺一不发):

  1. 证书张数 ≥ 2:openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE"
  2. 剩余有效期 > 30 天:同上管道接 | openssl x509 -noout -enddate
  3. TLS ≥ 1.2:openssl s_client -connect api.example.com:443 -tls1_1 必须失败
  4. SNI 正常:对纯 IP 加 -servername 能返回预期域名证书
  5. OCSP Stapling 可解析:-status 输出 OCSP Response Status: successful
  6. 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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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