微信小程序 HTTPS 证书安装与配置实战:Nginx/Tomcat 配置、证书链修复与真实报错排查
一、问题背景:小程序为什么强制 HTTPS,以及 90% 失败的真正根因
微信小程序的网络请求由 wx.request、wx.uploadFile、wx.downloadFile 等原生 API 发出,它们不像浏览器那样提供「继续访问」按钮:TLS 握手只要有一个环节不通过,请求就直接失败,开发者工具里通常只留下一句 request:fail ssl hand shake error 或笼统的 request:fail,真机调试甚至看不到细节。
微信客户端对服务端的硬性要求是:必须 HTTPS、必须是 443 端口、证书必须由公共信任的 CA 签发(自签名、私有 CA、IP 证书一律拒绝)、必须支持 TLS 1.2 及以上、域名必须完成 ICP 备案并在小程序后台「开发管理 → 开发设置 → 服务器域名 → request 合法域名」中登记。域名每月可修改次数有限(当前为 50 次/月,以后台提示为准),改错一次可能耽误一整天发版。
把大量工单归因后会发现,失败集中在下面五类:
- 证书链不完整:Nginx 里只配了站点证书,没拼中间证书。PC 浏览器会通过 AIA 自动补全,所以「电脑能打开、手机和小程序报错」几乎都是这个原因。
- 域名与 SAN 不匹配:证书只签了
example.com,请求却发往www.example.com,报ERR_CERT_COMMON_NAME_INVALID。 - 协议版本过低:服务端仍开放 TLS 1.0/1.1,被微信客户端直接拒绝。
- 证书过期:有效期规则已经变了。自 2020-09-01 起,CA/B Forum 规定公有 CA 签发的 TLS 证书最长有效期 398 天;Let’s Encrypt 固定 90 天。按 SC-081 排期,2026-03-15 起降为 200 天、2027-03-15 起 100 天、2029-03-15 起 47 天。「一年一装、到期再说」的做法已经彻底失效。
- 服务器时间偏差或 SNI 未开启:报
certificate is not yet valid,或多域名共用 IP 时返回了默认站点的证书。
二、前置准备:备案、解析、证书选型与 CSR 生成
动手前先确认三件事:域名已完成 ICP 备案(国内服务器必须)、A 记录已指向目标 IP、443 端口在安全组和防火墙中放行。用下面两条命令快速验证:
dig +short example.com
curl -I --connect-timeout 5 http://example.com
证书选型上,小程序场景用 DV(域名验证型)即可,微信不校验 OV/EV 标识。单域名证书只保护一个 FQDN;通配符证书 *.example.com 只覆盖一级子域,a.b.example.com 和裸域 example.com 都不在其中,必须把裸域单独写进 SAN。若用 OpenSSL 自行生成 CSR:
# RSA 2048
openssl req -new -newkey rsa:2048 -nodes
-keyout example.com.key -out example.com.csr
-subj '/C=CN/ST=Zhejiang/L=Hangzhou/O=Example/CN=example.com'
# 或 ECC P-256(握手更快,推荐)
openssl ecparam -genkey -name prime256v1 -out example.com.key
openssl req -new -key example.com.key -out example.com.csr
-subj '/CN=*.example.com'
拿到证书后,务必先做两项自检再上线:私钥与证书是否匹配、证书包含哪些 SAN。
openssl x509 -noout -modulus -in example.com.crt | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5 # 两行输出必须一致
openssl x509 -noout -subject -dates -ext subjectAltName -in example.com.crt
若使用 ECC 私钥,则改用 openssl pkey -pubout 比对公钥。证书文件统一转成 PEM(Base64,以 -----BEGIN CERTIFICATE----- 开头),DER 格式或带 BOM 的文件会导致 Nginx 启动直接报错。
三、实操一:用 acme.sh 申请免费证书并自动续期
Let’s Encrypt 证书有效期 90 天,微信完全认可,前提是必须做自动化续期。推荐 acme.sh,它不依赖 root、自带 cron 续期任务:
curl https://get.acme.sh | sh -s email=admin@example.com
source ~/.bashrc
acme.sh --set-default-ca --server letsencrypt
通配符证书只能走 DNS-01 验证,以阿里云 DNS 为例:
export Ali_Key='LTAI5txxxxxxxxxxxx'
export Ali_Secret='xxxxxxxxxxxxxxxxxxxxxxxx'
~/.acme.sh/acme.sh --issue --dns dns_ali
-d example.com -d '*.example.com' --keylength ec-256
单域名或已有站点根目录时,用 webroot 方式更简单:
acme.sh --issue -d example.com -d www.example.com -w /var/www/html
签发成功后,用 --install-cert 把证书「安装」到固定路径,并绑定重载命令——这是唯一正确的姿势,直接 cp 文件会在下次续期后失效:
acme.sh --install-cert -d example.com --ecc
--key-file /etc/nginx/ssl/example.com.key
--fullchain-file /etc/nginx/ssl/example.com.fullchain.pem
--reloadcmd 'systemctl reload nginx'
注意 --fullchain-file 才是「站点证书 + 中间证书」的完整链,--cert-file 只是叶子证书。确认续期任务已生效:
crontab -l | grep acme
acme.sh --list
acme.sh --renew -d example.com --force # 手动演练一次续期
不想用免费证书的,也可以在云厂商控制台申请 DV 证书(当前免费额度同样按 90 天签发),下载时务必选择「Nginx 格式」并包含 _chain.crt 中间证书文件。
四、实操二:Nginx 完整配置示例(含证书链与 TLS 1.2/1.3)
把证书放到 /etc/nginx/ssl/ 后,最小可用配置如下。ssl_certificate 必须指向 fullchain,顺序是站点证书在前、中间证书在后,写反了同样会握手失败:
server {
listen 80;
server_name example.com www.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on; # nginx 1.25.1+;旧版写 listen 443 ssl http2;
server_name example.com www.example.com;
ssl_certificate /etc/nginx/ssl/example.com.fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/example.com.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;
add_header Strict-Transport-Security 'max-age=31536000' always;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
三个细节值得单独说:其一,ssl_ciphers 只作用于 TLS 1.2,TLS 1.3 的套件由 OpenSSL 内置,无法也不需要通过该指令配置;其二,OCSP Stapling 需要 ssl_stapling on; 与 ssl_trusted_certificate 配合,但 Let’s Encrypt 已于 2025 年停止 OCSP 服务,其证书开启 stapling 无实际收益,商业 CA 证书可正常启用;其三,若同一 IP 承载多个站点,必须确保 server_name 与 SNI 匹配,否则微信会拿到默认站点的证书。
改完执行 nginx -t && systemctl reload nginx,切勿用 restart,reload 才能平滑切换证书。
五、实操三:Tomcat / Spring Boot / Node.js 的证书格式转换
Java 生态不能直接吃 PEM,需要把 fullchain 与私钥打包成 PKCS12,再按需转 JKS:
openssl pkcs12 -export
-in example.com.fullchain.pem
-inkey example.com.key
-name tomcat
-out example.com.p12
-passout pass:changeit
keytool -importkeystore
-srckeystore example.com.p12 -srcstoretype PKCS12 -srcstorepass changeit
-destkeystore example.com.jks -deststoretype JKS -deststorepass changeit
keytool -list -v -keystore example.com.jks | grep -i 'Certificate chain length'
输出 Certificate chain length: 3(叶子 + 中间 + 根)才算完整;如果只有 1,说明打包时漏了中间证书。Spring Boot 2.x/3.x 的配置:
server:
port: 443
ssl:
enabled: true
key-store: classpath:example.com.p12
key-store-type: PKCS12
key-store-password: changeit
key-alias: tomcat
enabled-protocols: TLSv1.2,TLSv1.3
传统 Tomcat 则在 server.xml 的 Connector 上配置 SSLEnabled='true'、keystoreFile、keystorePass、sslEnabledProtocols='TLSv1.2,TLSv1.3'。注意 JDK 8 早期版本默认不启用 TLS 1.3,升级到 8u261+ 或 JDK 11+ 更稳妥。
Node.js 侧同理,cert 必须读 fullchain 文件而不是单证书:
const https = require('https');
const fs = require('fs');
https.createServer({
key: fs.readFileSync('/etc/ssl/example.com.key'),
cert: fs.readFileSync('/etc/ssl/example.com.fullchain.pem')
}, app).listen(443);
使用云负载均衡(SLB/CLB)的用户,把 fullchain 与私钥分别粘贴到证书管理控制台即可,注意不要粘贴根证书(部分平台会因链过长报「证书格式错误」)。
- NGINX / APACHE / TOMCAT / IIS 证书配置 · SSL证书安装
- 服务器维护 · 网站代维护 · 服务器托管代维
- APP/小程序 HTTPS · SSL网站加密证书 · CA证书配置
六、方案对比:证书类型与部署方式怎么选
下表按小程序常见需求横向对比,价格区间为 2025 年国内市场参考价,实际以服务商报价为准:
| 方案 | 覆盖范围 | 有效期上限 | 价格区间 | 适用场景 |
|---|---|---|---|---|
| Let’s Encrypt DV 单域名 | 1 个 FQDN | 90 天(不可延长) | 免费 | 个人项目、可自动化续期 |
| Let’s Encrypt DV 通配符 | *.example.com(仅一级) | 90 天 | 免费 | 多子域 API 网关 |
| 商业 DV 单域名 | 1 个 FQDN | 398 天 | 约 300 元/年(含安装配置) | 不便自动化的传统 IDC 环境 |
| 商业 DV 通配符 | *.example.com + 裸域 | 398 天 | 约 600~1200 元/年(含代购与配置) | 多子域、多环境统一管理 |
| 多域名 SAN 证书 | 多个不同主域 | 398 天 | 按域名数递增 | api.example.com + api.example.net |
| OV/EV 证书 | 单域名/多域名 | 398 天 | 数千元/年 | 金融、政企合规要求 |
部署位置对比:
| 部署方式 | 证书格式 | 续期操作 | 常见坑 |
|---|---|---|---|
| Nginx 反向代理 | PEM(fullchain) | reload 即可 | 漏拼中间证书、证书顺序写反 |
| Tomcat / Spring Boot | PKCS12 / JKS | 需重新打包并重启 | 链长度只有 1、JDK 版本过低 |
| Node.js | PEM(fullchain) | 需重启进程 | cert 只读了叶子证书 |
| 云负载均衡 | PEM 粘贴 | 控制台替换 | 误粘根证书、私钥带密码 |
一句话结论:能上自动化就选 Let’s Encrypt + acme.sh,把 90 天续期交给 cron;必须走人工流程的环境再选 398 天的商业证书,但要在日历上提前 30 天提醒。
七、常见错误排查:真实报错与逐条定位命令
先掌握万能诊断命令,它会打印完整证书链和校验结果:
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null
输出中 Verify return code: 0 (ok) 才算通过;若为 20 (unable to get local issuer certificate) 就是链不完整。以下是最常撞见的几类真实报错:
curl: (60) SSL certificate problem: unable to get local issuer certificate——服务端未发送中间证书。修复:cat example.com.crt intermediate.crt > fullchain.pem,并在 Nginx 指向 fullchain。curl: (60) SSL: no alternative certificate subject name matches target host name 'www.example.com'——SAN 不含该域名。用openssl x509 -noout -ext subjectAltName -in fullchain.pem核对,必要时重签证书。- 小程序端
request:fail ssl hand shake error——优先查三处:TLS 版本是否 ≥1.2、证书链是否完整、SNI 是否返回正确证书。用nmap --script ssl-enum-ciphers -p 443 example.com查看协议支持情况。 nginx: [emerg] SSL_CTX_use_PrivateKey() failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)——证书与私钥不配对,回到第二节做 modulus 比对。nginx: [emerg] PEM_read_bio_X509_AUX() failed (SSL: error:0909006C:PEM routines:get_name:no start line)——文件不是 PEM,或复制时混入了 HTML/文本说明。用head -1 fullchain.pem确认首行是-----BEGIN CERTIFICATE-----。- Java 侧
java.security.cert.CertificateException: No subject alternative names present——客户端用 IP 直连而非域名,或 JKS 里只有自签证书。 - 浏览器
ERR_CERT_AUTHORITY_INVALID/SSL_ERROR_NO_CYPHER_OVERLAP——前者是自签或链断,后者是服务端套件与客户端无交集,放宽ssl_ciphers或补齐 ECDHE 套件。 x509: certificate has expired or is not yet valid——除了真的过期,还要检查服务器时间:timedatectl status,偏差超过 5 分钟即握手失败。
八、效果验证:从命令行到真机的四层确认
配置完成后不要直接提交审核,按下面四层依次验证。
第一层,协议与证书信息:
curl -I https://example.com
openssl s_client -connect example.com:443 -servername example.com /dev/null
| openssl x509 -noout -subject -dates -ext subjectAltName
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | grep 'Protocol'
期望看到 HTTP/2 200、notAfter 在未来 30 天以上、Protocol : TLSv1.3。
第二层,证书链完整性:
openssl crl2pkcs7 -nocrl -certfile /etc/nginx/ssl/example.com.fullchain.pem
| openssl pkcs7 -print_certs -noout
应至少列出两张证书(站点证书 + 中间证书),且站点证书排在第一位。
第三层,第三方评分:
curl -s 'https://api.ssllabs.com/api/v3/analyze?host=example.com&publish=off&all=done'
| grep -o '"grade": *"[A-F+]*"'
目标 A 及以上;若因 TLS 1.0/1.1 enabled 掉到 B,回第四节收紧 ssl_protocols。
第四层,真机验证:关闭微信开发者工具「详情 → 本地设置 → 不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」,用体验版在 iOS 与 Android 各测一次。两端都通过才算真正上线成功——很多链不完整的问题只在 Android 上暴露。
最后加一条到期监控,避免 90 天证书悄悄失效:
end=$(openssl s_client -connect example.com:443 -servername example.com /dev/null
| openssl x509 -noout -enddate | cut -d= -f2)
echo $end; date -d "$end" +%s
把剩余天数小于 20 天作为告警阈值接入监控系统即可。
常见问题
免费证书(Let’s Encrypt)能用于正式上线的小程序吗?
可以。微信只校验证书是否由受信任的公共 CA 签发、域名是否匹配、TLS 版本是否达标,并不区分免费或付费。唯一需要注意的是 Let’s Encrypt 有效期固定 90 天且不可延长,必须用 acme.sh 或 certbot 配置自动续期与 reload 钩子,否则 3 个月后小程序会突然全线报 request:fail。
通配符证书为什么保护不了 api.test.example.com?
因为 *.example.com 只匹配一级子域,api.test.example.com 属于二级子域,不在覆盖范围内;同样,裸域 example.com 也不被通配符覆盖。解决办法是签证书时把裸域写入 SAN(-d example.com -d '*.example.com'),二级子域则单独申请或改用多域名 SAN 证书。
为什么电脑浏览器访问正常,小程序和安卓手机却报 SSL 错误?
这是证书链不完整最典型的症状。PC 浏览器遇到缺失的中间证书时,会依据证书里的 AIA 地址自动下载补全;而微信客户端与 Android 系统不保证做这个动作,链一断就握手失败。修复方法是在服务端把中间证书拼到站点证书后面,并让 Nginx 的 ssl_certificate 指向 fullchain 文件。
证书有效期到底是 398 天还是 1 年?
公有 CA 签发的 TLS 证书最长有效期自 2020-09-01 起为 398 天,任何声称「一年期」的证书实际签发时长都不会超过这个上限。按 CA/B Forum SC-081 的排期,2026-03-15 起进一步缩短到 200 天,2027-03-15 起 100 天,2029-03-15 起 47 天,自动化续期将成为唯一可行方案。
可以直接用 IP 地址或自签名证书给小程序用吗?
不行。微信要求 request 合法域名必须是已备案的域名,不能填 IP;自签名证书与私有 CA 签发的证书不在系统信任库中,会直接返回 request:fail。内网调试请使用微信开发者工具关闭域名校验,但正式环境必须换成公共 CA 证书。
更换证书后需要在微信后台重新配置或重新提审吗?
只要域名没变,替换证书不需要修改后台配置,也不需要重新提交代码审核,客户端会自然使用新证书。只有当域名发生变化时,才需要到「开发管理 → 开发设置 → 服务器域名」更新 request 合法域名,注意每月修改次数有限,且修改后需重新编译小程序才会生效。