跳到主要内容
SSL 证书付费服务

微信小程序 HTTPS 证书安装与配置实战:Nginx/Tomcat 配置、证书链修复与真实报错排查

微信小程序 HTTPS 证书安装与配置实战:Nginx/Tomcat 配置、证书链修复与真实报错排查 — 微信小程序 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 与私钥分别粘贴到证书管理控制台即可,注意不要粘贴根证书(部分平台会因链过长报「证书格式错误」)。

六、方案对比:证书类型与部署方式怎么选

下表按小程序常见需求横向对比,价格区间为 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 合法域名,注意每月修改次数有限,且修改后需重新编译小程序才会生效。

内容审核

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