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

小程序域名 SSL 要求全解:TLS 1.2、证书链与 Nginx 配置实操指南

小程序域名ssl要求 — 小程序域名 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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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