小程序域名 SSL 要求全解:TLS 1.2、证书链与 Nginx 配置实操指南
小程序服务器域名必须启用 HTTPS,TLS 版本不低于 1.2,证书须由受信任 CA 签发且不支持自签名;iOS 端还要求证书有效期不超过 398 天、包含 SAN 扩展。 微信后台保存域名时会实时校验 HTTPS 与证书,境内主体域名必须完成 ICP 备案,且只能使用 443 端口、不能填 IP 或 localhost。 证书链必须完整下发:Nginx 的 ssl_certificate 应指向 fullchain.pem(叶子证书 + 中间证书),否则 Android 7.0 以下与部分 iOS 会报 unable to get local issuer certificate。 验证命令:openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 返回 Verify return code: 0 (ok),且 openssl x509 -noout -dates 的 notAfter 在 398 天内。 预算 0 元可用 Let's Encrypt 90 天证书配合 acme.sh 自动续期;预算 200-600 元/年可选 DigiCert、GeoTrust 的 DV 单域名证书,有效期 398 天。
一、小程序为什么强制 HTTPS?域名与证书不合规的根因是什么
据微信官方《小程序网络能力》文档,wx.request、wx.uploadFile、wx.downloadFile 与 wx.connectSocket 的服务器域名必须为 HTTPS / WSS,且 TLS 版本不得低于 1.2。HTTP 明文请求在真机上会被直接拦截,开发者工具里最常见的提示是 request:fail url not in domain list——很多人误以为是域名没配,其实是协议或 TLS 版本先被拒了。这条”小程序域名 SSL 要求”分四层校验,任何一层不过,表现都不一样。
| 校验层 | 执行方 | 硬性要求 | 不满足时的真实报错 |
|---|---|---|---|
| 域名准入 | 微信后台保存域名时 | 境内主体须 ICP 备案;必须 443 端口;禁止 IP、localhost、非标准端口 | 域名未备案 / 该域名未通过备案 |
| TLS 握手 | 微信客户端 | 协议版本 ≥ TLS 1.2 | request:fail ssl hand shake error |
| 证书链 | 系统根证书库 | 公共 CA 签发 + 下发完整中间证书 | unable to get local issuer certificate |
| iOS ATS | iOS 系统(微信是宿主 App) | TLS 1.2、SHA-256 签名、RSA ≥ 2048 位或 ECC ≥ 256 位、证书含 SAN、有效期 ≤ 398 天 | -1202(NSURLErrorDomain)/「此服务器的证书无效」 |
第二层和第四层是”Android 正常、iOS 报错”的高发区。微信作为宿主 App 同样受 Apple App Transport Security 约束:据 Apple 开发者文档,自 2017 年起 App Store 应用默认要求 TLS 1.2 + SHA-256 + RSA 2048 / ECC 256,且证书必须带 SAN 扩展(CN 字段已不被采信);自 2020-09-01 起新签发的 TLS 服务器证书有效期不得超过 398 天(原 825 天),超期证书在 iOS 上直接判为不受信任。这解释了为什么同一套 Nginx 配置,Android 手机正常、iPhone 却报 -1202。
第三层常被忽略:微信客户端使用系统根证书库校验,自签名证书、私有 CA、过期根证书一律不认;服务器必须主动下发完整中间证书链,否则 Android 7.0 以下及部分 iOS 版本会报 unable to get local issuer certificate。下面三条命令可在改 Nginx 之前先给线上域名做一次体检(OpenSSL 1.1.1+,-ext 参数需 1.1.1 及以上):
# 1) 强制只协商 TLS 1.2,验证是否满足微信最低版本要求
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null 2>/dev/null | grep -E "Protocol|Cipher"
# 期望:Protocol: TLSv1.2 / Cipher: ECDHE-RSA-AES128-GCM-SHA256(协商失败即 handshake failure)
# 2) 统计服务端下发的证书张数:1 张 = 缺中间证书,正常应为 2~3 张
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE"
# 3) 检查 SAN 扩展与有效期(iOS 要求 SAN 必填、剩余天数 ≤ 398)
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| openssl x509 -noout -dates -ext subjectAltName
提醒:Let’s Encrypt 自 2024 年起签发的证书有效期已缩短至 90 天,远低于 398 天上限,因此更现实的风险不是”超期”,而是忘记续期导致小程序线上接口整体不可用——续期失败后 iOS 端报错往往是「此服务器的证书无效」,Android 端则可能因缓存仍短暂可用,造成排查方向的误判。
二、从备案到上线:小程序域名 SSL 配置的 6 个实操步骤
很多开发者把「证书装上了」当成终点,结果在微信后台点保存时被拒,或者小程序真机请求报 request:fail ssl hand shake error。问题几乎都出在链顺序、协议版本或域名形态上。下面按上线顺序给出 6 步可复制的操作,覆盖从 ICP 备案到微信后台校验的完整闭环,也顺带把小程序域名 SSL 要求里最容易被忽略的细节讲清楚。
第 1 步:域名备案与解析。小程序服务器域名必须是已备案域名,在阿里云或腾讯云提交 ICP 备案,管局审核通常 7–20 个工作日。备案通过后把 api.example.com 以 A 记录指向服务器公网 IP,TTL 建议 600 秒(便于故障时快速切换)。生效后用 dig 确认,注意返回必须是公网 IP 而不是 CDN 的 CNAME:
# 只输出解析结果,确认 A 记录指向你的服务器公网 IP
dig api.example.com +short
# 期望输出示例:47.98.x.x
# 顺带看权威 NS 是否已同步(排查"本地生效、线上不生效")
dig api.example.com +trace | tail -20
第 2 步:选证书。小程序 API 域名只做机器间通信,DV(域名验证型)单域名证书足够,OV/EV 的组织信息对微信校验没有任何加分。选型对比如下:
| 方案 | 有效期 | 参考价格 | 续期方式 | 适用场景 |
|---|---|---|---|---|
| Let’s Encrypt DV | 90 天 | 0 元 | acme.sh 自动续期(cron) | 个人项目、测试环境、能跑定时任务 |
| DigiCert / GeoTrust DV 单域名 | 398 天 | 200–600 元/年 | 手动重签 | 不想维护自动续期的生产环境 |
| 通配符 *.example.com | 90 天或 1 年 | 0 元(LE,需 DNS-01)或千元级 | DNS-01 自动续期 | api / img / ws 等多子域名 |
据 Let’s Encrypt 官方文档,其证书有效期固定 90 天且不支持付费延长,因此自动化续期不是可选项而是必需项;acme.sh 默认在到期前 30 天续期。
第 3 步:生成 CSR 与私钥。在服务器上执行(OpenSSL 1.1.1 / 3.x 均适用):
openssl req -new -newkey rsa:2048 -sha256 -nodes
-keyout api.example.com.key
-out api.example.com.csr
-subj "/C=CN/O=Example/CN=api.example.com"
# -sha256 签名算法用 SHA-256(SHA-1 已被主流 CA 与浏览器拒绝)
# -nodes 私钥不加密,否则 Nginx 启动时会卡在输入密码
# -subj 免交互填写主题,CN 必须与域名完全一致
第 4 步:签发并合并证书链。CA 完成 DNS 或文件验证后签发,下载 Nginx 格式压缩包,得到 api.example.com.pem 与 api.example.com_ca.crt。合并顺序必须是「服务器证书 → 中间证书」,依据 RFC 5280 的证书路径构建规则,顺序颠倒会导致客户端无法从叶子证书回溯到受信根:
cat api.example.com.pem api.example.com_ca.crt > fullchain.pem
# 验证链是否完整(应输出 OK,且只列出一张中间证书)
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt fullchain.pem
# 直接看线上实际下发的链,缺中间证书时 s_client 会报
# "verify error:num=21:unable to verify the first certificate"
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null
第 5 步:部署 Nginx 并重载。把 fullchain.pem 与私钥放到 /etc/nginx/ssl/,私钥权限收紧到 600,然后写入站点配置:
chmod 600 /etc/nginx/ssl/api.example.com.key
chmod 644 /etc/nginx/ssl/fullchain.pem
# /etc/nginx/conf.d/api.conf
server {
listen 443 ssl;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 必须是含中间证书的链文件
ssl_certificate_key /etc/nginx/ssl/api.example.com.key;
ssl_protocols TLSv1.2 TLSv1.3; # 微信要求 TLS 1.2 及以上;nginx 1.23.4 起默认值才含 1.3
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
}
nginx -t && nginx -s reload
ss -lntp | grep :443 # 确认 0.0.0.0:443 处于 LISTEN
注意:nginx 1.23.4 之前的 ssl_protocols 默认值是 TLSv1 TLSv1.1 TLSv1.2,仍会协商已废弃的 TLS 1.0/1.1,务必显式写死。
第 6 步:微信后台配置与校验文件。登录 mp.weixin.qq.com,进入「开发 → 开发管理 → 服务器域名」,在 request 合法域名中填入 https://api.example.com——不能带端口、路径和查询串,端口只能是 443。保存时微信会实时发起 HTTPS 请求校验,这正是小程序域名 SSL 要求的硬性落点:证书受信、链完整、TLS ≥ 1.2、域名已备案。若使用 web-view 承载网页,还需把下载的 MP_verify_xxxxxxxx.txt 放到站点根目录,并确认可公开访问:
curl -I https://api.example.com/MP_verify_xxxxxxxx.txt
# 期望:HTTP/2 200,Content-Type: text/plain
# 若返回 404 或 301 跳转,微信校验会失败
最后做一次端到端自检,同时覆盖协议与链两项小程序域名 SSL 要求:
# 强制用 TLS 1.2 握手,能拿到证书说明协议版本达标
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null | grep "Protocol|Verify return code"
# 期望:Protocol : TLSv1.2 / Verify return code: 0 (ok)
# 检查证书剩余天数,避免上线后 30 天内突然过期
echo | openssl s_client -connect api.example.com:443 2>/dev/null
| openssl x509 -noout -dates -subject
常见报错对照:unable to verify the first certificate 是链顺序错或缺中间证书;sslv3 alert handshake failure 多为协议版本或加密套件不匹配(如服务端只开 TLS 1.3 而客户端库较旧);微信后台提示「域名不合法」则优先排查备案状态与是否误填了端口。这三类问题与 TLS 握手机制、证书链信任模型强相关,后续可结合 SNI、OCSP Stapling、HSTS 等主题继续展开。
三、Nginx 与 OpenSSL 配置示例(可直接复制)
Q:Nginx 1.20+ 的 443 server 块,最小可用的 TLS 配置怎么写?
下面这段可以直接复制,注释标了每一项的依据。据 Mozilla SSL Configuration Generator 的 intermediate(TLS 1.2 + TLS 1.3)模板,这是当前兼容性与安全性折中的默认推荐,也正好覆盖小程序域名 SSL 要求里“必须 TLS 1.2 及以上”这条硬门槛:
server {
listen 443 ssl;
# Nginx 1.25.1+ 用 http2 on; 1.20~1.24 请写成 listen 443 ssl http2;
server_name api.example.com;
# 只放行 TLS 1.2/1.3,禁用 CBC 套件与 RSA 密钥交换
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off; # 让客户端挑套件,移动端更易命中 TLS 1.3
ssl_session_cache shared:SSL:10m; # 10m 约缓存 4 万个会话,默认 none
ssl_session_timeout 1d; # 默认 5m,小程序长连接场景建议放大
ssl_session_tickets off;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 叶子 + 中间证书
ssl_certificate_key /etc/nginx/ssl/api.example.com.key;
ssl_stapling on; # 默认 off
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem; # 仅中间证书,用于校验 OCSP 响应
resolver 223.5.5.5 119.29.29.29 valid=300s; # 必须配置,否则 stapling 静默失效
resolver_timeout 5s;
}
Q:这三个 PEM 文件到底谁放哪?搞混会怎样?
| 文件 | 内容 | 对应指令 | 放错后的典型现象 |
|---|---|---|---|
| fullchain.pem | 叶子证书 + 中间证书 | ssl_certificate | 只放叶子证书时,小程序端报“证书链不完整”,iOS 真机直接握手失败 |
| chain.pem | 仅中间证书 | ssl_trusted_certificate | 写成 fullchain 会导致 OCSP 校验失败,stapling 不生效 |
| *.key | 私钥 | ssl_certificate_key | 权限 644 时存在泄露风险,应 chmod 600 |
开启 OCSP Stapling 后,客户端不必再单独向 CA 的 OCSP 服务发一次请求,少一个往返,实测握手延迟可降低约 100–300ms;这对小程序首屏冷启动的体感很明显。验证是否真的生效:openssl s_client -connect api.example.com:443 -servername api.example.com -status </dev/null 2>/dev/null | grep -A1 "OCSP Response Status",应看到 successful。
Q:HTTP 跳 HTTPS 和 HSTS 怎么写才不翻车?
server {
listen 80;
server_name api.example.com;
return 301 https://$host$request_uri; # 保留原始路径与查询串
}
server {
listen 443 ssl;
# ...上面的 TLS 配置...
add_header Strict-Transport-Security "max-age=31536000" always;
# 首次上线先写 max-age=300,观察 24 小时,确认无混合内容与内嵌 HTTP 资源后再改成 31536000
}
HSTS 一旦下发 31536000,浏览器在一年内拒绝任何降级回 HTTP 的尝试,回滚成本极高,所以“先 300 再拉满”是运维惯例;always 参数保证 4xx/5xx 响应也带这个头(Nginx 1.7.5+ 支持)。
Q:怎么用 OpenSSL 自查握手、有效期和证书链?
# 1) 强制用 TLS 1.2 握手,看签发者与到期时间
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
# 期望:notAfter 距今不超过 398 天(CA/B Forum 规定),issuer 为受信任 CA
# 若输出 handshake failure,说明 TLS 1.2 未启用或套件不匹配
# 2) 链完整性:叶子 + 中间证书至少 2 张
openssl s_client -connect api.example.com:443 -showcerts </dev/null 2>/dev/null | grep -c "BEGIN CERTIFICATE"
# 3) 本地校验整条链
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt
-untrusted /etc/nginx/ssl/chain.pem /etc/nginx/ssl/fullchain.pem
# 期望输出:/etc/nginx/ssl/fullchain.pem: OK
注意 -servername 不能省:SNI 缺失时 Nginx 会返回默认 server 块的证书,校验结果与实际业务域名不符。
Q:WSS 和业务域名校验文件怎么配?
# wx.connectSocket 只接受 wss://,必须透传 Upgrade
location /ws/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1; # 默认 1.0,不改无法升级
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600s; # 默认 60s,长连接会被误断
}
# 校验文件用 = 精确匹配,优先级高于前端 history 路由的 try_files
location = /MP_verify_xxxxxxxx.txt {
root /var/www/html;
default_type text/plain;
}
校验文件若被 location / 的 try_files $uri /index.html 兜住,会返回 HTML 而不是纯文本,微信校验会提示“文件内容不正确”——这也是小程序域名 SSL 要求之外最常被忽略的一环。
四、DV、OV、通配符与 ECC:小程序证书方案选型对比表
先给结论:六种方案一张表看完
下表的验证方式、有效期与兼容性来自各 CA 的 CPS 与微信官方文档;价格为 2024 年中国大陆 CA 代理商常见报价区间,仅供估算,实际以合同为准。
| 方案 | 验证方式 | 有效期 | 小程序兼容性 | 参考价格 |
|---|---|---|---|---|
| DV 单域名(Let’s Encrypt) | 域名 / DNS | 90 天,自动续期 | 完全兼容,需自动化 | 0 元 |
| DV 单域名(DigiCert / GeoTrust) | 域名 / DNS | 398 天 | 完全兼容 | 200–600 元/年 |
| DV 通配符 *.example.com | DNS | 398 天 | 兼容一级子域名 | 800–2000 元/年 |
| OV 单域名 | 企业资料 | 398 天 | 完全兼容,非强制 | 1500–4000 元/年 |
| ECC P-256 证书 | 同 DV | 398 天 | Android 5.0+ / iOS 9+ 兼容 | 同 DV 或上浮约 10% |
| 国密 SM2 证书 | 企业资料 | 398 天 | 微信客户端不支持 | 不建议 |
RSA 2048、ECC P-256、RSA 4096,到底该选哪个?
不确定客户端版本的老项目,选 RSA 2048:它仍在 CA/Browser Forum Baseline Requirements 允许的密钥长度下限之上,兼容面最广。新项目选 ECC P-256(即 secp256r1 / prime256v1),握手更快、证书体积约为同安全强度 RSA 的 1/3,微信客户端最低支持 Android 5.0,其系统信任库已覆盖主流 ECC 根证书,可放心使用。RSA 4096 的握手与验签开销比 2048 高约 30%,小程序 API 这类高频短连接场景没有收益。生成密钥时注意曲线名对应关系:
# 生成 P-256 私钥(prime256v1 等价于 secp256r1,别写成 secp256k1)
openssl ecparam -genkey -name prime256v1 -out ecc.key
# 核对证书实际使用的签名算法与公钥算法
openssl x509 -in fullchain.pem -noout -text
| grep -E "Signature Algorithm|Public Key Algorithm|Not After"
# ECC 证书典型输出:Public Key Algorithm: id-ecPublicKey / ASN1 OID: prime256v1
单域名、通配符、多域名 SAN,覆盖范围差在哪?
- 单域名只保护 api.example.com,不含 www.api.example.com,也不含裸域 example.com。
- 通配符 *.example.com 只覆盖一级子域名,a.b.example.com 不在范围内,需要单独加 SAN 或再买一张 *.b.example.com。
- 多域名 SAN 可在一张证书里放多个域名,上限由 CA 决定,常见为 100 个,适合 API 网关多租户场景。
Let’s Encrypt 免费证书能满足小程序域名 SSL 要求吗?
能。微信对小程序域名 SSL 要求只约束协议版本与证书有效性,不区分 DV/OV,据微信开放文档,服务器必须使用 TLS 1.2 及以上、证书由受信任 CA 签发且在有效期内。Let’s Encrypt 通过 ACME v2(RFC 8555)签发,有效期 90 天,官方推荐在到期前 30 天续期。真正需要评估的是运维能力:没有定时续期脚本的小团队,建议买 398 天付费 DV(该上限由 CA/Browser Forum 自 2020 年 9 月起强制),并确认 CA 提供 OCSP 与工单支持,以减少证书过期导致的线上故障。另外要注意,Android 7.1.1 及更早的系统信任库不含 ISRG Root X1,这类极老设备访问 Let’s Encrypt 证书可能失败,付费 DV 的根证书覆盖通常更老一些。
# Let's Encrypt 自动签发 + 续期后重载 Nginx
certbot certonly --webroot -w /var/www/acme -d api.example.com
--deploy-hook "nginx -s reload" # 续期成功才 reload,避免空跑
systemctl list-timers | grep certbot # 确认定时器已启用(默认每天两次)
为什么必须部署 fullchain 而不是叶子证书?
据 RFC 5280,客户端需要从叶子证书逐级构建到受信任根,中间证书缺失时链就断了。CA 下载页通常给两个文件:cert.pem(叶子)与 fullchain.pem(叶子 + 中间证书)。Nginx 的 ssl_certificate 必须指向 fullchain,ssl_certificate_key 指向私钥。只部署叶子的典型表现是 Android 端小程序报 request:fail ssl handshake error,iOS 端报 NSURLErrorServerCertificateUntrusted,而浏览器因为会自行补链,往往看不出问题——这是最容易踩的坑。
# 在线验证链完整性;返回 0 才算通过
openssl s_client -connect api.example.com:443 -servername api.example.com
-showcerts &1 | grep -E "verify|Verify return code"
# 缺中间证书时:verify error:num=21:unable to verify the first certificate
# 正确时:Verify return code: 0 (ok)
接入阿里云 CDN 或腾讯云 EdgeOne 时证书放在哪?
在 CDN 控制台的证书管理里同时上传证书内容(fullchain 全文)与私钥,HTTPS 配置中勾选 TLS 1.2 与 TLS 1.3,回源协议选 HTTPS,避免”用户到 CDN 加密、CDN 到源站明文”的断链。CDN 侧证书同样受 398 天限制,续期后需重新上传,建议把证书指纹纳入监控告警。
五、常见错误与排查:小程序 SSL 报错对照表
小程序端的 SSL 报错往往只有一句话,根因却横跨微信后台配置、证书链、协议版本、备案四层。下表把最常见的六种报错与验证动作对齐,后文给出逐条命令。
| 报错原文 | 典型根因 | 一行验证 |
|---|---|---|
request:fail url not in domain list |
域名未登记,或与实际请求的协议/端口/路径不一致 | 后台核对 request 合法域名是否为 https://api.example.com |
request:fail ssl hand shake error |
只开 TLS 1.0/1.1、链不完整、套件不含 AEAD | openssl s_client -tls1_2 -brief |
iOS「此服务器的证书无效」/ -1202 |
自签名、根不受信、有效期 >398 天、缺 SAN | openssl x509 -noout -text 看 SAN 与 notAfter |
unable to get local issuer certificate |
Nginx 只下发叶子证书,未带中间证书 | s_client -showcerts 数证书条数 |
| 「域名未备案」 | 境内主体未做 ICP 备案,或主体不一致 | 工信部备案系统查询域名 |
certificate has expired |
90 天证书未续期,或续期后未 reload | openssl x509 -noout -dates |
1. url not in domain list。微信只认「开发管理 → 服务器域名」里登记的 request 合法域名,且该项不带端口、不带路径、不支持通配符——https://api.example.com 与 https://example.com 是两条独立记录,https://api.example.com:8443/v1 一定失败。小程序域名 SSL 要求的第一条就是「443 端口 + 标准 HTTPS」,因此务必让业务域名直接落在 443。
2. ssl hand shake error。微信 iOS 端遵循 Apple ATS,据 Apple 开发者文档要求 TLS 1.2 以上、前向保密套件(ECDHE)与 AEAD 加密(AES-GCM/ChaCha20)。复测:
# OpenSSL 1.1.1+ 支持 -brief;期望输出 Protocol version: TLSv1.2 / Cipher: ECDHE-*-GCM
echo | openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 -brief
# 关键行:Verify return code: 0 (ok)
Nginx 侧最小可用配置(1.9.7+ 支持 TLSv1.3 需 1.13.0+ 与 OpenSSL 1.1.1+):
ssl_protocols TLSv1.2 TLSv1.3; # 默认值 TLSv1 TLSv1.1 TLSv1.2,必须显式收紧
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off; # 1.11.0+ 默认 off,交由客户端选序
ssl_session_cache shared:SSL:10m; # 默认 none,开启可降低握手开销
ssl_session_timeout 10m; # 默认 5m
3. iOS 证书无效 / -1202。Apple 自 2020-09-01 起要求 TLS 服务器证书有效期不超过 398 天;CA/B 论坛 SC-081 进一步规定 2026-03-15 起降至 200 天。自签名证书与缺少 SAN 的证书一律不受信(CN 字段早已被忽略)。核查:
openssl x509 -in fullchain.pem -noout -text | grep -A1 "Subject Alternative Name"
# 期望包含 DNS:api.example.com
openssl x509 -in fullchain.pem -noout -dates # 看 notBefore / notAfter 跨度
4. unable to get local issuer certificate。这是微信开发者工具(Node 运行时)与部分 Android 机型的典型症状:服务端只发叶子证书。拼接顺序必须是「叶子在前、中间在后」:
cat api.example.com.crt intermediate.crt > fullchain.pem # 顺序不可颠倒
# nginx.conf: ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key .../privkey.pem;
nginx -t && nginx -s reload
# 复核:输出应 ≥2 个 BEGIN CERTIFICATE
echo | openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts 2>/dev/null | grep -c "BEGIN CERTIFICATE"
5. 域名未备案。境内主体的小程序域名 SSL 要求之上还有一道硬门槛:ICP 备案,且备案主体须与小程序主体一致或存在明确关联(同一主体、子公司或授权书)。境外主体无需备案,但 HTTPS 与证书合规不豁免。备案结果可在工信部「ICP/IP/域名信息备案管理系统」(beian.miit.gov.cn)核验。
6. certificate has expired。Let’s Encrypt 证书有效期 90 天,据其官方文档建议在到期前 30 天续期。续期后不 reload 等于没续:
certbot renew --dry-run # 演练,确认 webroot/dns 插件可用
acme.sh --cron --home ~/.acme.sh # acme.sh 定时任务,--reloadcmd "nginx -s reload" 可自动生效
systemctl list-timers | grep -E "certbot|acme" # 确认定时器存在
nginx -s reload
openssl x509 -in fullchain.pem -noout -dates # 对比 notAfter 是否已更新
排查顺序建议固定为:先看微信后台域名登记(配置层)→ 再跑
s_client(协议与链层)→ 最后查备案(合规层)。三层自上而下,能覆盖本节 90% 以上的小程序 SSL 报错。
六、如何验证小程序域名 SSL 配置已生效
验证不能只看”浏览器能打开”。小程序域名 SSL 要求落到可观测项上其实是三件事:证书链完整、协议版本达标、微信客户端认可。下面按从底层到应用层的顺序给出可直接执行的检查。
1)证书链、有效期、域名匹配,一条命令看完
# -servername 显式传 SNI,否则多站点服务器会返回默认站点的证书,结论无效
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null
| openssl x509 -noout -dates -subject -issuer
# 单独核对 SAN(微信校验的是 SAN,不是 CN;CN 字段在新证书中已废弃)
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null
| openssl x509 -noout -ext subjectAltName
输出中需同时满足三点:notAfter 距今在 398 天以内(CA/Browser Forum 对公开信任 TLS 证书的有效期上限,Let’s Encrypt 现签发 90 天证书);issuer 为受信任 CA(如 C=US, O=Let's Encrypt, CN=R3);DNS:api.example.com 出现在 SAN 中。此外注意 Verify return code: 0 (ok),非 0 通常意味着中间证书缺失。
2)协议边界:TLS 1.1 必须被拒绝
openssl s_client -connect api.example.com:443 -tls1_1 </dev/null # 期望握手失败
openssl s_client -connect api.example.com:443 -tls1_2 </dev/null | grep Protocol
openssl s_client -connect api.example.com:443 -tls1_3 </dev/null | grep Protocol
第一条应输出 sslv3 alert handshake failure 或 no protocols available,说明 TLS 1.0/1.1 已关闭;后两条分别返回 TLSv1.2 与 TLSv1.3。TLS 1.3 由 RFC 8446 定义,微信 8.x 客户端已支持,关闭它不会报错但会损失一次往返的握手性能。
3)curl 端到端确认
curl -vI https://api.example.com/health --tlsv1.2 --max-time 10
# 关键三行:
# SSL certificate verify ok.
# TLSv1.2 (OUT), TLS handshake, Finished
# TLS_AES_256_GCM_SHA384 ← 若为 TLS1.3 会话则显示此套件
若出现 curl: (60) SSL certificate problem: unable to get local issuer certificate,即服务端未下发中间证书,属于典型的证书链配置问题,按第五节(Nginx ssl_certificate 需拼接「站点证书 + 中间证书」)处理。
4)在线工具复核与交叉比对
| 工具 | 验证维度 | 通过标准 | 局限 |
|---|---|---|---|
| SSL Labs(ssllabs.com/ssltest) | 协议版本、套件、证书链、签名算法 | 评级 A 及以上,无 SHA-1 签名 | 缓存结果最长 24 小时 |
| MySSL | 证书链完整性、OCSP Stapling | 链完整、Stapling 为”已开启” | 不评估业务可用性 |
| openssl s_client | 链、有效期、SAN | verify code 0、SAN 匹配 | 需手动逐项判读 |
| 微信开发者工具 | 微信侧真实校验结果 | 请求成功、无域名类报错 | 仅覆盖当前调试环境 |
5)微信侧最终确认:开发者工具「详情 → 本地设置」中取消勾选「不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」,重新编译;再用真机预览走同一流程。此勾选一旦保留,微信会跳过全部校验,本地一切正常而线上失败——这是小程序域名 SSL 要求最容易被绕过的一环。
6)持续监控,别等过期才发现
# blackbox_exporter 0.24+ 的 ssl 模块默认暴露证书最早到期时间(Unix 秒)
# prometheus 告警表达式:剩余不足 30 天
probe_ssl_earliest_cert_expiry - time() < 30 * 86400
# Zabbix 5.0+ 可用内置键值取回 JSON,再取 x509.not_after
zabbix_get -s 127.0.0.1 -k 'web.certificate.get[api.example.com,443]'
据 Let’s Encrypt 文档,ACME 续期失败最常见的两类原因是 80 端口验证路径被拦截与 CAA 记录不匹配,因此监控应同时覆盖证书到期时间与 HTTP-01 验证端点的可达性。
七、证书自动化续期与 CDN 场景补充
acme.sh 3.x 怎么给小程序后端域名签一张 ECC 证书?
微信小程序要求服务端证书由受信任 CA 签发且证书链完整,因此 ACME 客户端必须走公网可验证的 HTTP-01 或 DNS-01 流程。以 webroot 方式为例(Nginx 站点根目录为 /var/www/html):
# 1) 安装 acme.sh(v3.x),-s 后的参数会传给安装脚本,用于注册 ACME 账号邮箱
curl https://get.acme.sh | sh -s email=ops@example.com
source ~/.bashrc # 加载 acme.sh 别名
# 2) 签发 ECC P-256 证书(--keylength ec-256)
# 注意:acme.sh 自 v3.0.0 起默认 CA 已改为 ZeroSSL,
# 要用 Let's Encrypt 必须显式指定 --server letsencrypt
acme.sh --issue -d api.example.com
--webroot /var/www/html
--keylength ec-256
--server letsencrypt
| 参数 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|
--keylength |
2048(RSA) | 2048 / 3072 / 4096 / ec-256 / ec-384 | ec-256 即 ECC P-256,握手更快、包更小 |
--server |
zerossl(v3.0.0+) | letsencrypt / letsencrypt_test / zerossl / buypass / google | 指定 CA 目录地址 |
--days |
60 | 1–90 | 剩余有效期低于该值才续期;Let’s Encrypt 官方建议剩余 30 天续期 |
| crontab 条目 | 0 0 * * * |
— | 安装时写入,每天 00:00 执行 acme.sh --cron,并非网传的 03:00 |
证书装进 Nginx 后,续期了怎么自动生效?
不要手动 cp,用 --install-cert 把文件映射关系和 reload 动作一起登记进 acme.sh 的配置,之后每次续期都会自动执行:
acme.sh --install-cert -d api.example.com --ecc
--key-file /etc/nginx/ssl/api.example.com.key
--fullchain-file /etc/nginx/ssl/fullchain.pem
--reloadcmd "nginx -t && nginx -s reload"
关键点:ECC 证书的每条命令都要带 --ecc,否则 acme.sh 会去找同名 RSA 证书并报 Cert path not found。另外 --reloadcmd 以安装 acme.sh 的那个用户身份执行,若该用户无写 /etc/nginx/ssl 或执行 reload 的权限,reload 会静默失败——文件已更新、Nginx 仍在用旧证书,这正是很多”续期成功但浏览器仍报证书过期”的根因;先用 nginx -t && nginx -s reload 做校验更稳妥。
怎么确认续期任务真的在跑?
acme.sh --list # 查看 Next Renew 时间
acme.sh --cron --force # 强制演练一次,验证 reloadcmd 是否成功
crontab -l | grep acme # 确认定时任务存在
接入 CDN 后,证书该放在哪一侧?
小程序访问的是 CDN 边缘节点,客户端只校验边缘证书,所以证书必须上传到 CDN(如阿里云「证书服务 → CDN → HTTPS 配置」),并在该页开启 TLS 1.2 与 TLS 1.3、打开「强制跳转 HTTPS」。源站建议同样保留 HTTPS,回源协议选 HTTPS 而非 HTTP,避免 CDN 到源站之间出现明文链路或因源站证书与回源域名不匹配导致 502。务必注意:CDN 上的证书不会跟随源站 acme.sh 自动续期,需在到期前重新上传,或调用 CDN API 自动化——据阿里云 CDN 文档,证书过期后 HTTPS 访问会直接失败。
测试域名 test-api.example.com 能复用证书或用自签名吗?
不能。证书按 SAN 校验,复用会触发域名不匹配;自签名证书不在信任链内,小程序真机调试会直接失败。正确做法是单独签发,并先用 Let’s Encrypt 测试环境跑通 ACME 流程(配额宽松、不占生产速率限制):
# 先在 staging 验证解析与 webroot 是否可用
acme.sh --issue -d test-api.example.com --webroot /var/www/html
--keylength ec-256 --server letsencrypt_test
# 验证通过后,删掉测试证书,切生产环境重签
acme.sh --remove -d test-api.example.com --ecc
acme.sh --issue -d test-api.example.com --webroot /var/www/html
--keylength ec-256 --server letsencrypt
staging 签出的证书不被信任,仅用于验证链路,切勿部署到线上;据 Let’s Encrypt 文档,生产环境对同一注册域名有每周 50 张的限额,反复调试务必留在 staging。
八、与小程序相关的其他 TLS 概念:WSS、web-view、OCSP 与 HSTS
wx.connectSocket 必须用 wss:// 吗?Nginx 反向代理要改什么?
是。微信官方文档明确 wx.connectSocket 的 url 只接受 wss://,明文 ws:// 会被直接拒绝,底层握手仍是 TLS 1.2+,因此第 1~7 节讲的证书链、协议版本要求对它同样成立。Nginx 默认 proxy_http_version 是 1.0,直接反代会因缺少 Upgrade 头导致 101 切换失败,前端报 WebSocket connection to 'wss://…' failed。正确写法:
# Nginx 1.18+ / 1.24 验证通过,路径 /etc/nginx/conf.d/miniprogram.conf
server {
listen 443 ssl;
http2 on; # 1.25.1+ 写法;旧版用 listen 443 ssl http2;
server_name api.example.com; # 必须与小程序后台"request 合法域名"逐字一致
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 必须含中间证书,否则部分安卓机握手失败
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3; # 1.23.4 之前默认含 TLSv1/1.1,需显式收紧
location /ws/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1; # 默认 1.0,必须改
proxy_set_header Upgrade $http_upgrade; # 透传 Upgrade: websocket
proxy_set_header Connection "upgrade"; # 加引号,避免普通请求发送空 Connection
proxy_set_header Host $host;
proxy_read_timeout 3600s; # 默认 60s,长连接需放大
}
}
注意 WebSocket 与 API 共用 443 时,证书 CN/SAN 必须覆盖同一域名,不要给 ws 子域单独签发后再混用,否则小程序侧会报证书与域名不匹配。
web-view 业务域名为什么也会报错?
web-view 加载的页面需先在微信公众平台配置”业务域名”并上传校验文件,校验文件必须能通过 HTTPS 直接访问,且证书合规。可临时用 Nginx 精确匹配返回:
location = /a1b2c3d4e5f6.txt {
default_type text/plain;
return 200 "8f3c...校验串n"; # 内容需与微信后台下载的文件完全一致
}
页面里若还引用 http:// 图片或脚本,会被内核拦截,控制台出现 Mixed Content: The page at 'https://…' was loaded over HTTPS, but requested an insecure image 'http://…'. This request has been blocked.——这就是混合内容问题,必须全站 HTTPS,用 Content-Security-Policy: upgrade-insecure-requests 兜底。
OCSP Stapling 开了却没生效?
据 Mozilla SSL Configuration Generator 与 Nginx 官方文档,ssl_stapling 默认 off,且缺少 resolver 或 ssl_trusted_certificate 时会静默失效(不报错)。
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem; # 根+中间证书,缺此项 stapling 不工作
resolver 223.5.5.5 119.29.29.29 valid=300s; # 默认无 resolver
resolver_timeout 5s;
验证命令(OpenSSL 1.1.1+):
openssl s_client -connect api.example.com:443 -servername api.example.com -status /dev/null
| grep -E "OCSP Response Status|OCSP response"
# 期望:OCSP Response Status: successful (0x0)
# 若输出 "OCSP response: no response sent",说明 stapling 未生效
作用是把 OCSP 查询从客户端转移到服务器,减少握手延迟——对首屏冷启动敏感的小程序场景收益明显。
HSTS 能直接上一年吗?
不建议。HSTS 由浏览器缓存,一旦下发长 max-age 且某个子域不支持 HTTPS,回滚成本极高。灰度做法:
# 首次上线:5 分钟,观察 1~2 天
add_header Strict-Transport-Security "max-age=300" always;
# 确认所有子域均支持 HTTPS 后,再改为
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
always 保证 4xx/5xx 响应也带该头;注意 HSTS 只对浏览器生效,小程序原生请求不读该头,它解决的是 web-view 与分享落地页的降级问题。
为什么自签名证书一定过不了?
除了链不受信任,还有证书透明度(CT)这一层:Chrome 自 2018 年起、iOS 自 10.3 起要求公开信任的证书携带 SCT(签名证书时间戳),否则拒绝。据 Let’s Encrypt 与 RFC 6962 文档,主流 CA 默认通过证书内嵌 SCT 列表或 TLS 扩展下发满足该要求。
| 证书类型 | 是否含 SCT | 链是否受信任 | 小程序可用 |
|---|---|---|---|
| Let’s Encrypt / DigiCert 等公开 CA | 是(默认内嵌) | 是 | 可用 |
| 企业内部 CA | 否 | 否(需手动装根) | 不可用 |
| 自签名 | 否 | 否 | 不可用 |
这也解释了为什么”小程序域名 SSL 要求”里从不允许导入自定义根证书:微信客户端不复用系统信任库之外的自建 CA。上线前可用 openssl s_client -connect 域名:443 -showcerts 配合 curl -vI https://域名 双向确认链完整性与 CT 信息。
是。微信官方要求服务器域名必须使用 HTTPS/WSS,TLS 版本不低于 1.2,且证书须由受信任 CA 签发,不支持自签名证书。iOS 端还叠加 ATS 要求,证书有效期不得超过 398 天并包含 SAN 扩展。
不可以。微信后台只接受已备案的域名,不能填 IP、localhost,也不能带端口和路径,默认走 443。境内主体还需完成 ICP 备案,否则保存域名时会提示「域名未备案」。
可以,Let's Encrypt 证书被微信客户端信任,兼容小程序。区别主要在有效期与维护方式:Let's Encrypt 为 90 天,需要 acme.sh 或 certbot 自动续期;付费 DV 常见 398 天有效期,并提供工单支持,适合没有自动化脚本的团队。
通常是 iOS ATS 校验更严格:证书有效期超过 398 天、缺少 SAN 扩展、使用 SHA-1 签名,或服务器未下发中间证书。用 openssl s_client -connect 域名:443 -servername 域名 查看 Verify return code 与证书链,再对照修复。
先确认服务器已启用 TLS 1.2 与 TLS 1.3,执行 openssl s_client -connect api.example.com:443 -tls1_2 看是否握手成功;再检查证书链是否完整、密码套件是否包含 ECDHE。常见原因是只开了 TLS 1.0/1.1,或 Nginx 只配置了叶子证书未配置 fullchain。
目前不建议。微信客户端使用系统根证书库校验,不信任国密根证书,国密 SM2 证书在小程序真机上通常无法完成握手。选择 RSA 2048 或 ECC P-256 的公开信任证书更稳妥。
提前 30 天续期,用 acme.sh –install-cert 的 –reloadcmd 参数在证书更新后自动执行 nginx -s reload;续期后可用 openssl x509 -noout -dates 核对 notAfter,并在微信开发者工具关闭「不校验合法域名」复测一次。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。