微信小程序 SSL 证书配置全流程:申请、Nginx 部署、报错排查与真机验证
微信小程序的 wx.request、wx.connectSocket、wx.uploadFile 等接口所在域名必须部署受信任 CA 签发的 SSL 证书、支持 TLS 1.2 及以上并下发完整证书链,否则真机直接报 request:fail ssl handshake error,且不支持 IP、localhost 与非 443 端口。 证书链不完整是最高发原因:Nginx 的 ssl_certificate 必须指向「服务器证书 + 中间证书」拼接的 fullchain.pem,用 openssl s_client -showcerts 检查时 BEGIN CERTIFICATE 至少出现 2 次、Verify return code 为 0。 微信小程序后台「开发管理-开发设置-服务器域名」每月可修改 50 次,域名填 https://api.example.com 即可,不要带端口、路径或通配符。 TLS 版本与套件按 Mozilla Intermediate 配置:ssl_protocols TLSv1.2 TLSv1.3,套件使用 ECDHE-RSA-AES128-GCM-SHA256 等 AEAD 组合,关闭 TLS 1.0/1.1 与 RSA-1024、SHA-1 证书。 证书有效期将持续缩短(CA/B Forum SC-081:2026-03-15 起最长 200 天、2027-03-15 起 100 天),必须用 acme.sh 或 certbot 自动化续期并配置到期告警。
微信小程序为什么必须配好 SSL 证书?真机报错的根本原因有哪些?
为什么开发者工具里接口一切正常,真机却报 request:fail ssl handshake error?据微信官方《小程序开发指南 · 网络》章节说明,wx.request、wx.connectSocket、wx.uploadFile、wx.downloadFile 请求的服务器域名必须为 HTTPS / WSS,TLS 版本不低于 1.2;域名不支持 IP 地址、localhost 和非 443 端口,在小程序后台「开发 → 开发设置 → 服务器域名」里填写时也不能带端口和路径。换句话说,证书链、协议版本、SNI 三者任一不达标,接口就直接不可用——这也是微信小程序 SSL 证书配置里最容易被跳过、却最先暴露的一步。
第二道门槛是签发者。微信客户端只信任系统根证书库中的公共 CA。自签名证书、企业内网 CA 证书,以及「只部署服务器证书、不部署中间证书」的半链状态都会被直接拒绝。典型症状是开发者工具能过、真机不能过:开发者工具底层校验相对宽松,而真机走微信自研网络栈,严格按 RFC 5280 逐级验证到根。因此 Nginx 上应始终指向 fullchain 而非单张站点证书:
server {
listen 443 ssl;
http2 on; # Nginx 1.25.1+ 写法;旧版本用 listen 443 ssl http2;
server_name api.example.com; # 必须与小程序后台填写的域名完全一致
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/TLSv1.1,务必显式声明
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off; # 与 Mozilla 中间兼容配置一致
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
}
怎么确认是不是半链?-showcerts 会打印服务端实际下发的全部证书,计数为 1 就说明中间证书缺失(OpenSSL 1.1.1 / 3.x 通用):
# 返回 1 = 只有站点证书(半链,Android 大概率握手失败);返回 2~3 = 链完整
openssl s_client -connect api.example.com:443 -servername api.example.com
-showcerts /dev/null | grep -c "BEGIN CERTIFICATE"
# 顺带确认协议与套件
openssl s_client -connect api.example.com:443 -servername api.example.com
/dev/null | grep -E "Protocol|Cipher"
Android 端完全依赖服务端下发的中间证书补齐信任链,而 iOS 在部分场景下可通过证书的 AIA 字段自动抓取,于是出现「iOS 正常、部分 Android 机型失败」的割裂现象——这不是玄学,是证书链分发策略差异。
| 真机报错 / 现象 | 最可能根因 | 一条命令定位 |
|---|---|---|
request:fail ssl handshake error(仅部分 Android) |
证书链不完整,缺中间证书 | openssl s_client -showcerts 计数证书张数 |
ERR_CERT_COMMON_NAME_INVALID / 域名不符 |
SNI 未命中,返回默认站点证书 | openssl s_client -servername 域名 看返回的 subject |
| 握手直接失败、无 HTTP 状态码 | 服务端只开 TLS 1.0/1.1,或 RSA-1024、SHA-1 签名 | nmap --script ssl-enum-ciphers -p 443 域名 |
| 开发者工具正常,真机提示域名不合法 | 域名未 ICP 备案或后台未保存 | 查小程序后台服务器域名列表 |
算法与协议同样致命。Android 10 及以上与微信 8.x 默认拒绝 TLS 1.0/1.1、RSA-1024 密钥与 SHA-1 签名证书(参见 RFC 8446 与 CA/Browser Forum 基线要求,公共 CA 自 2016 年起已停止签发 SHA-1 证书)。用 openssl x509 -in fullchain.pem -noout -text | grep -E "Signature Algorithm|Public-Key" 可快速核对。
SNI 是第三个隐形坑。同一 IP 的 443 端口承载多个域名时,若 Nginx 未用 server_name 精确匹配,或前置 SLB / CDN 未透传 SNI,客户端会拿到默认站点证书,报 ERR_CERT_COMMON_NAME_INVALID。
最后是流程问题。域名须先完成 ICP 备案,小程序后台才能保存为合法域名;服务器域名每月仅 50 次修改额度,改完还需重新编译并清理开发者工具缓存,否则请求仍发往旧域名。建议在申请阶段就用 Let’s Encrypt 或商业 CA 签发含中间证书的完整包,一次性规避后续排查成本。
微信小程序 SSL 证书配置的完整实操步骤(6 步走完)
很多人以为「上传证书 → 后台填域名」就完事了,结果真机一跑就报 request:fail ssl hand shake error。问题几乎都出在中间某个环节被跳过。下面这 6 步是微信小程序 SSL 证书配置的最小完整闭环,每一步都给出可复制命令和判断标准,按顺序走完再灰度。
第 1 步:域名形态先定死,填错后面全白做
据微信官方《服务器域名配置》文档,request 合法域名与 socket 合法域名是两个独立列表,格式和限制不同,同一域名要分别填两次;两者都不支持通配符和 IP,端口只能是 443。
| 项目 | request 合法域名 | socket 合法域名 |
|---|---|---|
| 填写格式 | https://api.example.com |
wss://api.example.com |
| 是否共用 | 独立列表,需分别添加 | 独立列表,需分别添加 |
通配符 *.example.com |
不支持,保存时校验失败 | 不支持,保存时校验失败 |
| 端口 | 仅 443,不能显式写端口 | 仅 443,不能显式写端口 |
第 2 步:生成私钥与 CSR,或直接自动签发
# 手工方式,OpenSSL 3.0.13 实测通过
# -newkey rsa:2048 生成 2048 位 RSA 私钥;-nodes 私钥不加密(否则 Nginx 启动需交互输密码)
# -subj 的 CN 必须等于域名,虽然现代校验以 SAN 为准,但 CA 仍会比对
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"
# 自动方式:DNS-01 校验,无需开放 80 端口,适合纯 API 域名
acme.sh --issue -d api.example.com --dns dns_ali
第 3 步:拼接证书链,顺序不能反
# 服务器(叶子)证书在前,中间证书在后
cat api.example.com.pem chain.pem > fullchain.pem
# 验证顺序:输出的第一个 subject 必须是你的域名
openssl crl2pkcs7 -nocrl -certfile fullchain.pem |
openssl pkcs7 -print_certs -noout
顺序颠倒后,部分 Android 机型和微信内置浏览器不会自动补链,直接握手失败——这正是「电脑上正常、真机报错」的典型成因。
第 4 步:上传并收紧权限
install -d -m 700 /etc/nginx/ssl
install -m 600 -o root -g root fullchain.pem api.example.com.key /etc/nginx/ssl/
若 Nginx worker 用户读不到私钥,启动会直接失败并给出真实报错:
nginx: [emerg] SSL_CTX_use_PrivateKey_file("/etc/nginx/ssl/api.example.com.key") failed
(SSL: error:8000000D:system library::Permission denied)
第 5 步:写入 443 server 块并平滑生效
server {
listen 443 ssl;
http2 on; # Nginx ≥1.25.1;旧版写 listen 443 ssl http2;
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; # Nginx 1.23.0 起的默认值即为此
ssl_session_cache shared:SSL:10m; # 参考 Mozilla SSL 配置生成器的 intermediate 档
ssl_session_timeout 10m;
}
# 校验并热加载,不中断现有连接
nginx -t && systemctl reload nginx
# 期望输出:syntax is ok / test is successful
第 6 步:后台配置 + 真机验证
# ① 证书是否可信、有效期是否正常
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result}n' https://api.example.com/
# 期望 200 0(0 表示校验通过)
# ② 链是否完整、SNI 是否命中正确证书
openssl s_client -connect api.example.com:443 -servername api.example.com
-showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -dates -ext subjectAltName
两条都通过后,回微信公众平台填好第 1 步的两个域名,开发者工具执行「清缓存 → 全部清除」再重新编译,用「预览」扫码上真机。iOS 与 Android 对证书链的处理策略不同(参见 RFC 5280 路径校验规则),只在模拟器验证等于没验证。这套微信小程序 SSL 证书配置流程的关键,是把「拼接顺序」「私钥权限」「真机复核」三个高频坑前置到上线之前。
配置示例:Nginx 1.24、Apache 2.4 与宝塔面板的具体参数怎么写?
Nginx 1.24 的最小可用片段到底该怎么写?把下面整段存成 /etc/nginx/conf.d/api.example.com.conf,nginx -t 通过后 reload 即可,路径按你的实际证书目录替换:
# 适用:Nginx 1.24.x(1.25.1 起 listen 里的 http2 参数被标记 deprecated)
server {
listen 80;
server_name api.example.com;
return 301 https://$host$request_uri; # 小程序只允许 https,80 必须跳转
}
server {
listen 443 ssl http2; # 1.25.1+ 改成 listen 443 ssl; 再加一行 http2 on;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 服务器证书 + 中间证书
ssl_certificate_key /etc/nginx/ssl/api.example.com.key; # 私钥,chmod 600
ssl_protocols TLSv1.2 TLSv1.3; # 不要写 TLSv1.1,微信基础库已不兼容弱协议
ssl_session_cache shared:SSL:10m; # 1m ≈ 4000 个会话,10m ≈ 4 万
ssl_session_timeout 10m;
ssl_session_tickets off; # 关闭 ticket,保住前向保密
# 加密套件:Mozilla SSL Configuration Generator v5.7 的 Intermediate 档
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off; # 现代客户端下由客户端择优,Mozilla 明确推荐 off
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem; # 只放中间证书,不是 fullchain.pem
resolver 223.5.5.5 119.29.29.29 valid=300s;
resolver_timeout 5s;
add_header Strict-Transport-Security "max-age=300" always; # 首次上线先 300 秒,观察一周再改 31536000
location / { proxy_pass http://127.0.0.1:8080; }
}
OCSP 装订是最容易“配了等于没配”的一项:如果你把 ssl_trusted_certificate 也指向 fullchain.pem,Nginx 会在 error_log 里打印 [warn] "ssl_stapling" ignored, issuer certificate not found for certificate,装订静默失效。原因是 fullchain 的第一张就是服务器证书本身,Nginx 需要的是能签它的签发者(中间 CA)。同理,用 openssl s_client -connect api.example.com:443 -status 验证时,只有看到 OCSP Response Status: successful 才算真生效。
Apache 2.4.52 怎么写?注意 SSLStaplingCache 必须写在 VirtualHost 外面,写进去会启动失败;另外从 2.4.8 起 SSLCertificateChainFile 已废弃,证书链直接拼进 SSLCertificateFile 指向的 fullchain.pem:
# Debian/Ubuntu: /etc/apache2/sites-available/api.example.com.conf
SSLStaplingCache "shmcb:logs/stapling-cache(150000)" # 150000 字节 ≈ 3 万条 OCSP 记录
<VirtualHost *:443>
ServerName api.example.com
SSLEngine on
SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCipherSuite HIGH:!aNULL:!MD5:!3DES
SSLCertificateFile /etc/letsencrypt/live/api.example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/api.example.com/privkey.pem
SSLUseStapling on
</VirtualHost>
宝塔 / 1Panel 面板用户最容易踩哪个坑?三个粘贴框的语义和 Nginx 参数是一一对应的,只贴服务器证书就是最常见的证书链不全来源:
| 面板输入框 | 对应文件 | Nginx 参数 | 贴错的典型后果 |
|---|---|---|---|
| 证书(公钥) | cert.pem / 域名.crt | ssl_certificate | — |
| 私钥(KEY) | privkey.pem | ssl_certificate_key | key values mismatch |
| 证书链 | chain.pem(中间证书) | fullchain 的拼接来源 / ssl_trusted_certificate | 真机 request:fail ssl hand shake error |
证书与私钥不匹配时,Nginx 会直接拒绝启动,报错形如 nginx: [emerg] SSL_CTX_use_PrivateKey("...") failed (SSL: error:05800074:x509 certificate routines::key values mismatch),用 openssl x509 -noout -modulus -in fullchain.pem | openssl md5 与 openssl rsa -noout -modulus -in priv.key | openssl md5 对比两串 MD5 是否一致即可定位。据 Let’s Encrypt 文档,fullchain.pem 已包含中间证书,因此 Nginx 场景直接引用 fullchain 即可,Apache 场景则注意不要再单独写 SSLCertificateChainFile。HSTS 的实现细节可参考 RFC 6797,OCSP 装订的协议基础见 RFC 6066 的 status_request 扩展。
证书类型与部署方案怎么选?DV、通配符与源站、CDN 对比
Q1:小程序接口只挂一个域名,选哪种证书最省钱?
起步阶段直接用免费 DV 单域名证书。Let’s Encrypt 由 ISRG Root X1 根证书签发,微信内置浏览器与主流 Android 7.1.1+/iOS 10+ 均信任该根,有效期 90 天、0 元;据 Let’s Encrypt 官方速率限制文档,单注册域名每周签发上限 50 张、完全限定域名(FQDN)每周 5 张,正常业务远够用。阿里云、腾讯云的免费 DV 证书同样 0 元,但有效期只有 3 个月,且单账号有额度限制(腾讯云免费证书默认每账号 20 张/年)。商业 DV 约 200–800 元/年,溢价买到的是 1 年有效期、发票和工单支持,兼容性上与免费证书没有差别——所以微信小程序 SSL 证书配置的第一步不是”买贵的”,而是先确认能否自动化续期。
Q2:通配符证书到底覆盖哪些域名?
*.example.com 只匹配一级子域:api.example.com、ws.example.com 都能用,但 example.com 本身和 a.b.example.com 这类多级子域不在覆盖范围内,必须额外追加 SAN。另外 Let’s Encrypt 的通配符证书只能走 DNS-01 验证(不支持 HTTP-01),DNS API 自动化是前提:
# acme.sh 3.x,通过 DNS-01 签发通配符证书(Let's Encrypt,有效期 90 天)
export Ali_Key="LTAI5t****" # 阿里云 RAM 子账号 AccessKey,仅授权 AliyunDNSFullAccess
export Ali_Secret="****"
acme.sh --issue --dns dns_ali
-d example.com # 必须单独写裸域,*.example.com 不覆盖它
-d '*.example.com' # 覆盖 api / ws 等一级子域
--keylength ec-256 # ECDSA P-256,握手更快,微信端兼容
# 安装证书并让 Nginx 平滑重载
acme.sh --install-cert -d example.com --ecc
--key-file /etc/nginx/ssl/example.com.key
--fullchain-file /etc/nginx/ssl/example.com.pem
--reloadcmd "nginx -t && systemctl reload nginx"
Q3:证书装源站还是装 CDN?
| 方案 | 源站证书 | 回源链路 | 常见故障 |
|---|---|---|---|
| 仅装源站 | 必须是公网可信 CA | 客户端直连,无中间层 | 续期后忘记 reload → 证书过期 |
| 装 CDN(腾讯云 EdgeOne / 阿里云 CDN),回源 HTTP | 可用免费证书甚至自签 | 明文 | 源站安全组须只放行 CDN 回源 IP |
| 装 CDN,回源 HTTPS | 需单独配置”回源证书” | TLS | 漏配回源证书 → 502 / 握手失败 |
最容易被忽略的是第三行:CDN 边缘证书配好了,但回源证书这一层空着,浏览器侧看着是”小绿锁”,小程序里却报 request:fail ssl hand shake error。做微信小程序 SSL 证书配置时,CDN 与源站要当成两条独立的证书链路分别验证。注意微信小程序 wx.request 强制 HTTPS 且要求 TLS 1.2 及以上(据微信开放文档),回源链路同样要满足。
Q4:国内机房用海外 CA 的证书会变慢吗?
差在 OCSP/CRL 响应。纯国内机房访问海外 CA 的 OCSP 响应超时,可能让首次握手多花 200–500ms。解决办法是开启 OCSP 装订,由 Nginx 缓存响应后随握手一起下发(ssl_stapling 自 Nginx 1.3.7 起可用,默认 off):
# /etc/nginx/conf.d/api.example.com.conf
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/example.com.pem; # 必须是含根与中间证书的完整链,否则装订静默失效
resolver 223.5.5.5 119.29.29.29 valid=300s; # Nginx 需自行解析 OCSP 地址
resolver_timeout 5s;
# 验证是否真的装订成功(输出 "OCSP Response Status: successful (0x0)" 才算生效)
# openssl s_client -connect api.example.com:443 -servername api.example.com -status /dev/null | grep -i "OCSP Response Status"
Q5:为什么”有效期趋势”现在就得进选型清单?
CA/Browser Forum 已通过 SC-081 提案:2026-03-15 起证书最长有效期降至 200 天,2027-03-15 起 100 天,2029-03-15 起 47 天。手工续期在 90 天时代就已频繁出事,到 47 天时完全不可行。因此选型时把”是否支持 ACME 自动签发 + 自动部署 + 到期告警”和价格、类型放在同一张表里评估:Let’s Encrypt 与 acme.sh/certbot 组合天然满足;商业证书要确认 CA 是否提供 ACME 端点或 API;OV/EV 约 1000–5000 元/年、需营业执照核验 1–3 个工作日,小程序端并不展示企业实名信息,除非面向 B 端客户有合规审计要求,一般业务选 DV 即可。
微信小程序 SSL 常见报错与排查方法(附真实错误信息)
先给结论:真机报 request:fail ssl handshake error.,九成是证书链不完整(只部署了叶子证书、漏了中间证书)或服务端仍在放行 TLS 1.0/1.1。微信官方文档明确要求小程序服务器域名必须支持 TLS 1.2 及以上,iOS 侧还要过 ATS 校验,要求 SHA-256 签名、RSA ≥ 2048 位或 ECC ≥ 256 位——这两条是后面所有排查的判定基线。
| 报错原文 | 根因 | 一条命令定位 | 修复动作 |
|---|---|---|---|
| request:fail ssl handshake error.(真机) | 证书链不完整 / TLS < 1.2 | openssl s_client -showcerts | 换成 fullchain.pem,协议抬到 TLSv1.2+ |
| net::ERR_CERT_COMMON_NAME_INVALID | SAN 不含该域名,或 SNI 落到默认站点 | openssl x509 -ext subjectAltName | 补发含全部域名的证书;配置 server_name |
| net::ERR_CERT_AUTHORITY_INVALID | 自签名 / 私有 CA 证书上了线 | 看 issuer 是否为公共 CA | 换公共 CA(如 Let’s Encrypt)证书 |
| net::ERR_SSL_PROTOCOL_ERROR、iOS -1202 | 协议或套件不匹配(RSA-1024、SHA-1) | grep Protocol 看协商结果 | 禁用旧协议,换 2048 位以上 SHA-256 证书 |
| 此服务器的证书无效 / 证书已过期 | notAfter 已过(Let’s Encrypt 仅 90 天) | openssl x509 -dates | 续期并加 30 天到期告警 |
排查顺序建议固定成一条线,逐层排除比反复改 Nginx 配置快得多:域名解析 → 443 端口可达 → 证书链张数 → SAN 匹配 → TLS 版本与套件 → 小程序后台域名白名单。前一层不通,后一层的输出没有参考价值。
# 第 1 层:解析与连通性(telnet 不通就与证书无关,先查安全组/防火墙)
dig +short api.example.com
telnet api.example.com 443
# 第 2、5 层:一次握手看清协议、套件、证书链与校验结果
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null |
grep -E "Verify return code|Protocol|Cipher|s:|i:"
# 正常输出示例(openssl 1.1.1 / 3.x):
# depth=1 ... i:... ← 中间证书,缺这一层就是链不完整
# depth=0 ... s:api.example.com
# Protocol : TLSv1.3
# Cipher : TLS_AES_128_GCM_SHA256
# Verify return code: 0 (ok) ← 非 0 即为链/信任问题
# 数一下服务端到底发了几张证书,只有 1 张 = 漏配中间证书
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null |
grep -c "BEGIN CERTIFICATE"
链完整之后再看 SAN。注意小程序后台每配置一个 request 合法域名,证书 SAN 就必须覆盖一个,通配符证书只匹配一级子域,*.example.com 不覆盖 a.b.example.com(RFC 6125 的匹配规则)。
# 第 3、4 层:核对 SAN 与有效期(对 fullchain.pem 执行即可,取的是第一张叶子证书)
openssl x509 -noout -ext subjectAltName -in /etc/nginx/ssl/fullchain.pem
# 输出示例:DNS:api.example.com, DNS:www.example.com
openssl x509 -noout -dates -issuer -in /etc/nginx/ssl/fullchain.pem
# notBefore=Jun 1 00:00:00 2025 GMT
# notAfter=Aug 30 00:00:00 2025 GMT ← 距此不足 30 天就该告警续期
# issuer=C=US, O=Let's Encrypt, CN=R11 ← 出现自己的私有 CA 名即 AUTHORITY_INVALID
协议层最常见的残留是配置模板里写死的旧参数。nginx 1.23.0 起 ssl_protocols 的默认值已改为 TLSv1.2 TLSv1.3,但 1.22 及更早版本默认仍包含 TLSv1/1.1,从老机器迁移配置时极易带过来。按 Mozilla SSL Configuration Generator 的 intermediate 档位改:
# /etc/nginx/conf.d/api.conf —— 适用 nginx ≥ 1.13.0(TLSv1.3 支持起点)
server {
listen 443 ssl;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 必须是全链,勿只放 cert.pem
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3; # 显式关闭 TLSv1/1.1
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off; # TLS1.3 下由客户端选套件,保持 off
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
}
# 改完执行 nginx -t && nginx -s reload,再回到上面的 s_client 复验
最后别忘了第 6 层:小程序后台的 request 合法域名是精确匹配的,且不支持 IP、不支持端口、必须是 https。真机与开发者工具表现不一致时,优先怀疑工具侧走了代理或缓存了旧证书——清缓存后仍报错,才回到 s_client 的输出继续看 Verify return code 那一行。
如何验证微信小程序的 SSL 证书配置已经生效?
证书部署完不等于生效——Nginx reload 只代表配置被读取,真正的判据是”握手能谈成、链能验通、微信能放行”。下面按”命令行 → 微信侧 → 第三方评级 → 长期监控”四层逐级验证,任何一层失败都不算完成微信小程序 SSL 证书配置。
第一验:TLS 版本双栈是否都通。先用 curl 强制 TLS 1.2(--tlsv1.2/--tls-max 需 curl ≥ 7.54.0),再单独跑 TLS 1.3:
- HTTPS证书申请 · SSL证书安装部署 · 证书续费
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- SSL/HTTPS 证书配置 · 证书安装 · 证书申请
# 验 TLS 1.2(小程序基础库对 TLS 1.2 是硬要求)
curl -vI https://api.example.com --tlsv1.2 --tls-max 1.2 2>&1 | grep "SSL connection"
# 期望输出:* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
# 验 TLS 1.3(RFC 8446,可选但推荐,需 curl ≥ 7.52.0 + OpenSSL 1.1.1+)
curl -vI https://api.example.com --tlsv1.3 2>&1 | grep "SSL connection"
# 若返回 "unsupported protocol" 或握手失败,说明 Nginx ssl_protocols 未含 TLSv1.3
若第一条报 sslv3 alert handshake failure,多半是 Nginx 只开了 TLS 1.3 或证书算法与客户端不兼容;第二条报错则检查 ssl_protocols TLSv1.2 TLSv1.3; 是否漏写(Nginx 1.13.0 起默认值才含 TLSv1.3)。
第二验:签发者、有效期与 OCSP 装订。据 OpenSSL 文档,-status 会发送 status_request 扩展,服务端装订了 OCSP 响应才会回显:
openssl s_client -connect api.example.com:443 -servername api.example.com -status </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
# 输出示例:
# subject=CN = api.example.com
# issuer=C = US, O = Let's Encrypt, CN = R3 ← 必须是中间 CA,不是根、更不是自签
# notAfter=Oct 12 08:00:00 2025 GMT
# 只看 OCSP 装订结果(应出现 OCSP Response Status: successful)
openssl s_client -connect api.example.com:443 -servername api.example.com -status </dev/null 2>/dev/null | grep -A2 "OCSP Response Status"
第三验:链是否完整(最常见的”半链”故障)。小程序真机与 iOS 不缓存中间证书,缺中间 CA 会在 curl 里正常、在手机上必现 net::ERR_CERT_AUTHORITY_INVALID:
openssl s_client -showcerts -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| grep -c "BEGIN CERTIFICATE" # 期望 ≥ 2(叶子 + 中间)
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| grep "Verify return code" # 期望:Verify return code: 0 (ok)
第四验:微信侧放行。微信开发者工具默认勾选”不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书”,这会让所有证书问题被静默吞掉。到「详情 → 本地设置」取消勾选该项,然后真机预览(模拟器不校验真机网络栈),在 vConsole 的 Network 面板点开任一请求,确认 Protocol 列为 h2/https/1.1 且 TLS 版本 ≥ 1.2。据微信开放文档,小程序要求 TLS ≥ 1.2 且证书须被系统信任。
| 验证手段 | 能查出什么 | 判据 |
|---|---|---|
| curl –tlsv1.2 / –tlsv1.3 | 协议版本可用性、ALPN 协商 | 两行 “SSL connection using” 均出现 |
| openssl s_client -status | issuer 是否正确、notAfter、OCSP 装订 | issuer 为中间 CA + OCSP successful |
| openssl s_client -showcerts | 链完整性(半链) | BEGIN CERTIFICATE ≥ 2 且 Verify return code: 0 |
| myssl.com / Qualys SSL Labs | 整体评级、弱协议与套件 | A 级及以上,且未启用 TLS 1.0/1.1 |
第三方评级重点看三项:证书链完整、同时支持 TLS 1.2 与 1.3、TLS 1.0/1.1 已关闭。评级为 B 通常是套件含 CBC 或未开 HSTS,可参考 Mozilla SSL Configuration Generator 的 intermediate 配置对齐。
长期监控:别等过期才发现。Prometheus blackbox_exporter 的 probe_ssl_earliest_cert_expiry 返回 Unix 时间戳,直接算剩余秒数做三级告警:
# blackbox.yml 片段
modules:
https_2xx:
prober: http
http:
valid_tls_versions: [TLS12, TLS13] # 低于 1.2 直接判失败
preferred_ip_protocol: ip4
# PromQL:到期前 30/15/7 天三级告警
probe_ssl_earliest_cert_expiry - time() < 86400 * 30 # warning
probe_ssl_earliest_cert_expiry - time() < 86400 * 15 # critical
probe_ssl_earliest_cert_expiry - time() < 86400 * 7 # page
Let’s Encrypt 证书有效期 90 天,用 certbot 自动续期时务必配置 --deploy-hook "nginx -s reload",否则续期成功但 Nginx 仍加载旧证书——这类”续了却没生效”的故障,只有上述 openssl notAfter 检查能第一时间发现。
证书续期怎么自动化?acme.sh 与 certbot 的落地配置
微信小程序 SSL 证书配置不是“签一次就完事”:据 Let’s Encrypt 官方文档,证书有效期 90 天,建议在剩余 30 天前完成续期。自动化的最小闭环是“定时检查→续签→安装→reload Nginx→到期告警”。acme.sh 与 certbot 都能实现,但默认 CA、定时任务和证书安装方式不同。
acme.sh 3.0.7 怎么安装,并把 CA 固定到 Let’s Encrypt?
# 安装 acme.sh 3.0.7;email 用于注册 ACME 账户,安装器会写入每日 crontab
curl https://get.acme.sh | sh -s email=ops@example.com
# acme.sh 3.x 默认 CA 可能是 ZeroSSL,显式切换到 Let's Encrypt
~/.acme.sh/acme.sh --set-default-ca --server letsencrypt
# 验证:应看到每天 0 点执行的 --cron 任务
crontab -l | grep acme.sh
~/.acme.sh/acme.sh --list
安装后每天执行一次 --cron,默认 --days 60,对 90 天证书约在到期前 30 天续签;可手动演练:~/.acme.sh/acme.sh --cron --home ~/.acme.sh。据 acme.sh 文档,--set-default-ca 会持久化到账户配置,后续签发无需重复指定。
阿里云 DNS 自动签发怎么做?为什么 CDN 全站加速更适合 DNS-01?
# 阿里云 RAM 子账号需具备 AliyunDNSFullAccess;密钥会被 acme.sh 保存到 account.conf
export Ali_Key="LTAI5txxxxxxxx"
export Ali_Secret="xxxxxxxxxxxxxxxx"
# DNS-01 签发,不占用 80/443;通配符证书只能走 DNS-01
~/.acme.sh/acme.sh --issue --dns dns_ali
-d api.example.com -d '*.example.com'
--keylength ec-256
据 RFC 8555,DNS-01 通过 _acme-challenge TXT 记录证明域名控制权。当小程序后端走 CDN 全站加速、源站 80 端口被 CDN 回源或防火墙占用时,HTTP-01 常超时,DNS-01 更稳。*.example.com 不覆盖根域,若小程序也请求 example.com,需再加 -d example.com。--keylength ec-256 生成 ECDSA P-256 证书;acme.sh 默认 RSA 2048。
证书如何落到 Nginx,并保证续期后自动 reload?
# 首次安装证书;续期成功后 acme.sh 会重新复制文件并执行 reloadcmd
~/.acme.sh/acme.sh --install-cert -d api.example.com
--key-file /etc/nginx/ssl/api.key
--fullchain-file /etc/nginx/ssl/fullchain.pem
--reloadcmd "systemctl reload nginx"
# 私钥权限建议:Nginx master 以 root 启动时可读,worker 不需要直接读
chown root:root /etc/nginx/ssl/api.key
chmod 600 /etc/nginx/ssl/api.key
nginx -t
--install-cert 会把安装参数写入续期配置,之后每次续签成功都会重跑 --reloadcmd;systemctl reload nginx 不会中断现有连接。若只改证书不 reload,Nginx 仍会使用旧证书。
certbot 2.11 怎么配?RSA 与 ECDSA 双证书要注意什么?
# 1) 演练:走 staging 环境,不消耗生产速率限制
certbot renew --dry-run
# 2) 正式续期并 reload;--deploy-hook 只在成功续期后执行,会写入 renewal 配置
certbot renew --deploy-hook "systemctl reload nginx"
# 3) 查看所有 lineage 与到期时间
certbot certificates
# 4) 双证书:Certbot 2.0 起默认 --key-type ecdsa,RSA 必须显式指定且用不同 cert-name
certbot certonly --nginx -d api.example.com --cert-name api-ecdsa --key-type ecdsa
certbot certonly --nginx -d api.example.com --cert-name api-rsa --key-type rsa
据 Certbot 文档,--dry-run 使用 staging 环境验证续期链路;--deploy-hook 仅在证书真正更新后触发。RSA 与 ECDSA 是两条独立 lineage,需分别签发、分别续期,certbot renew 会遍历全部任务。Nginx 可在同一 server 块配置多张 ssl_certificate 以兼容不同客户端。
| 维度 | acme.sh 3.0.7 | certbot 2.11 |
|---|---|---|
| 安装方式 | curl https://get.acme.sh | sh |
apt/dnf/snap 安装系统包 |
| 默认 CA | ZeroSSL,需 --set-default-ca 切 Let’s Encrypt |
Let’s Encrypt |
| 自动任务 | 安装即写 crontab,每日 --cron |
systemd timer 或 cron,每日 renew |
| DNS-01 | 内置 dns_ali 等 DNS API |
需安装对应 DNS 插件 |
| 证书落地 | --install-cert + --reloadcmd |
--deploy-hook 或 renewal 配置 |
| 适用场景 | 轻量脚本、DNS API、多 CA 切换 | 系统包管理、双证书、标准运维 |
续期失败的高频原因有哪些?
- DNS API 密钥过期或权限不足:阿里云返回
InvalidAccessKeyId.NotFound或SignatureDoesNotMatch;更新Ali_Key/Ali_Secret后重跑签发。 - 80 端口验证被 CDN 或防火墙拦截:certbot 报
Timeout during connect (likely firewall problem);改用 DNS-01,或放行/.well-known/acme-challenge/。 - 私钥权限被改动:Nginx reload 报
cannot load certificate key ... Permission denied;恢复chmod 600与属主后nginx -t。 - reload 命令失败:
systemctl reload nginx返回非 0,acme.sh 会保留旧证书;先查nginx -t与系统日志。
最后兜底是到期告警,不要只依赖续期日志:
# 剩余不足 30 天时返回非 0,可接入 Prometheus textfile 或企业微信机器人
openssl x509 -checkend 2592000 -noout -in /etc/nginx/ssl/fullchain.pem
|| echo "WARN: api.example.com 证书将在 30 天内到期"
续期成功后,微信小程序 SSL 证书配置还应做一次真机验证:openssl s_client -connect api.example.com:443 -servername api.example.com 检查证书链完整,再关闭开发者工具“不校验合法域名”走真机请求,确认无证书链或域名不匹配报错。
WSS、HTTP/2 与文件上传场景下还有哪些额外要求?
Q:wx.connectSocket 的 wss 域名为什么不能和 request 域名共用?
据微信官方《小程序服务器域名配置》文档,request、uploadFile、downloadFile 与 socket 是四组独立白名单:socket 合法域名只接受 wss://,生产环境按 443 端口配置最稳妥。漏配时真机报 connectSocket:fail url not in domain list,开发者工具勾选“不校验合法域名”可绕过,真机不行。这也是微信小程序 SSL 证书配置里最容易漏的一步——证书本身没问题,白名单没加。反向代理还必须透传 Upgrade 与 Connection 头(RFC 6455 要求),否则 Nginx 返回 400 或握手后立即断开:
# /etc/nginx/conf.d/ws.conf —— 适用 Nginx 1.24 / 1.25
map $http_upgrade $connection_upgrade { # 必须放在 http{} 块
default upgrade;
'' close;
}
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;
location /ws/ {
proxy_pass http://127.0.0.1:9001;
proxy_http_version 1.1; # WebSocket 需要 1.1
proxy_set_header Upgrade $http_upgrade; # 透传 Upgrade
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s; # 默认 60s,长连接需放大
}
}
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket"
-H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ=="
https://api.example.com/ws/
# 期望 HTTP/1.1 101 Switching Protocols;400 多为 Upgrade 头未透传
Q:Nginx 开 HTTP/2 的写法为什么网上一半是错的?
Nginx 1.25.1 起 listen ... http2 被弃用并告警 "the listen ... http2 directive is deprecated",改为独立指令。先 nginx -v 确认版本,再二选一:
# Nginx 1.24.x 及更早
listen 443 ssl http2;
# Nginx 1.25.1+:listen 的 http2 参数已弃用
listen 443 ssl;
http2 on;
CDN 回源若降级为 HTTP/1.1,连接复用受 keepalive_requests 限制,小程序高并发下首包与排队时间明显上升。用 curl -I --http2 https://api.example.com 看是否返回 HTTP/2 200,或 openssl s_client -alpn h2 -connect api.example.com:443 </dev/null | grep ALPN 确认协商到 h2。
Q:wx.uploadFile 老是 60 秒超时,只换证书有用吗?
没用。微信侧 timeout 默认 60000ms,服务端 Nginx client_max_body_size 默认 1m(据 nginx.org ngx_http_core_module 文档)、proxy_read_timeout 默认 60s(ngx_http_proxy_module)。20MB 文件弱网必超时,前端报 uploadFile:fail timeout,Nginx 侧常见 413 或 504:
location /api/upload {
client_max_body_size 20m; # 默认 1m,超出返回 413 Request Entity Too Large
proxy_read_timeout 120s; # 默认 60s
proxy_send_timeout 120s; # 默认 60s
proxy_request_buffering off; # 大文件边收边转,降低磁盘占用
proxy_pass http://127.0.0.1:8080;
}
wx.uploadFile({ url: 'https://api.example.com/api/upload',
filePath, name: 'file', timeout: 120000 }) // 默认 60000ms
Q:后端要求 mTLS,小程序能配合吗?
不能。wx.request / wx.uploadFile 没有客户端证书参数,后端 ssl_verify_client on 会让小程序直接握手失败。可行路径是在小程序与后端之间加网关做单向认证转换:
| 方案 | 小程序侧 | 网关/后端 | 结论 |
|---|---|---|---|
| 直接 mTLS | 不支持导入客户端证书 | ssl_verify_client on | 不可行 |
| 网关终结 TLS + mTLS 回源 | 普通单向 HTTPS | 网关持有客户端证书 | 推荐 |
| 证书下发到客户端 | 无 API 可加载 | — | 不可行 |
Q:SAN 多域名证书怎么确认没漏配?
把证书覆盖的域名与小程序后台 request、socket 列表逐一 diff。漏一个,该域名整条链路握手失败:
openssl s_client -connect api.example.com:443 -servername api.example.com /dev/null
| openssl x509 -noout -ext subjectAltName
# 输出示例:DNS:api.example.com, DNS:upload.example.com, DNS:ws.example.com
若 socket 域名 ws.example.com 不在 SAN 中,微信报 connectSocket:fail ssl handshake failed,而 request 域名正常,极易误判为“证书整体有效”。Let’s Encrypt 会把申请时提交的全部域名写入 SAN,签发后仍应以上述命令复核,别只看浏览器地址栏的小锁。
可以。Let's Encrypt(ISRG Root X1 根证书)以及阿里云、腾讯云签发的免费 DV 证书都能被微信客户端信任,前提是下发完整证书链并支持 TLS 1.2。需要注意的是 Android 7.1.1 以下的老设备不信任 ISRG Root X1,若用户机型跨度大,建议做一次真机抽样验证。
不能。据微信官方文档,服务器域名只支持域名形式,不支持 IP 地址、localhost,也不支持在域名后附加端口号,HTTPS 与 WSS 默认走 443。如果后端服务监听在 8443 等端口,需要用 Nginx 或负载均衡在 443 上做反向代理。
先执行 openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts,检查返回的证书张数与 Verify return code;若只有 1 张证书或返回码非 0,说明证书链不完整,把中间证书与服务器证书拼成 fullchain.pem 后 reload 即可。若链正常,再检查是否禁用了 TLS 1.2。
两者都要考虑。证书装在 CDN 上负责小程序到边缘节点的握手,源站若被 CDN 以 HTTPS 回源访问,还需要一份回源证书(可以是免费 DV 或自签)。只配其中一层是常见的 502 与握手失败来源。
不需要也无法直接配置。小程序端的 wx.request 不支持携带客户端证书,只能走标准的单向 TLS 认证。如果后端系统强制 mTLS,需要在小程序与后端之间增加一层 API 网关,由网关完成与后端的双向认证。
只能覆盖一级子域。*.example.com 可以覆盖 api.example.com、ws.example.com,但不覆盖 example.com 本身,也不覆盖 a.b.example.com 这类二级子域。若接口分散在多级子域下,建议改用多域名 SAN 证书,并逐一核对 SAN 列表。
从握手与信任链角度没有本质区别,两者都能被微信客户端正常校验。差异主要在有效期(免费证书 90 天,商业 DV 通常 1 年)、赔付保障、OCSP 响应速度与技术支持。如果团队已有成熟的 acme.sh 自动化续期体系,免费证书完全够用;反之付费证书能减少续期运维负担。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。