微信小程序 HTTPS 证书申请与部署全流程:CSR 生成、Nginx/Tomcat 配置、真实报错排查与验证
一、问题背景与根因:小程序为什么“必须”HTTPS
微信小程序的所有网络能力——wx.request、wx.uploadFile、wx.downloadFile、wx.connectSocket——都强制走 HTTPS/WSS。这已经是客户端的强制校验,不只是建议:任何一项不满足,都会在真机上直接失败。而微信开发者工具默认勾选“不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书”,所以常常出现“工具里跑得通、真机报错”的典型情况。
小程序对服务端有四项硬性约束:
- 域名必须完成 ICP 备案(境内主体),并在小程序后台「开发管理 → 开发设置 → 服务器域名」中配置。不支持 IP、不支持 localhost、不支持通配符域名、不支持非 443 端口;
- 证书必须由受信任的公共 CA 签发,自签名证书、私有 CA 证书一律被拒绝;
- 必须下发完整证书链(服务器证书 + 中间证书),缺一段就会在部分 Android 机型上握手失败;
- 协议版本要求 TLS 1.2 及以上,密钥交换需支持 ECDHE 前向保密,签名算法 SHA-256 及以上。
根因在于两端信任模型不同:iOS 走 App Transport Security(ATS),要求 TLS 1.2+、支持前向保密的密码套件、证书链可追溯到系统信任根;Android 走系统 CA Store(7.0 起应用可自定义信任锚)。微信客户端内置了自己的校验逻辑,任何一环(过期、域名不匹配、链不完整、弱算法)都会中断连接,统一抛出 fail ssl hand shake error。所以排查必须靠服务端日志加 openssl s_client 逐层验证,而不能凭经验猜。
二、证书选型与有效期新规:398 天与 90 天
先说两个最容易被旧文章误导的数字。第一,公开信任的 TLS 证书最长有效期被限制为 398 天(CA/Browser Forum 与主流浏览器的共同要求),任何“买 2 年、3 年证书”的方案,实际都是签发 398 天证书到期后重签,“多年期”只是把续签服务打包售卖。第二,Let’s Encrypt 证书有效期固定 90 天,官方建议剩余 30 天时自动续期(acme.sh 默认 60 天触发续期)。行业已确定分阶段继续缩短至 200 天、100 天、47 天,采购时以 CA 实际签发结果为准,不要按“年”做容量规划。
小程序场景的选型逻辑很简单:微信不校验证书是 DV 还是 OV,只校验信任链和域名匹配,因此DV 证书完全够用。真正需要 OV 的是两类情况:一是行业监管或支付通道要求(部分银行、支付机构在商户审核时要求 OV/EV);二是 H5 落地页需要在浏览器里展示企业实名信息。
| 类型 | 典型产品 | 有效期 | 覆盖范围 | 适用场景 |
|---|---|---|---|---|
| 免费 DV | Let’s Encrypt / ZeroSSL | 90 天,需自动续期 | 单域名、SAN 多域名、通配符(DNS-01) | 小程序 API 域名、测试环境 |
| 付费 DV | 单域名 / 通配符证书 | 最长 398 天 | 单域名、SAN 多域名、*.example.com | 生产 API、需要 SLA 与人工支持 |
| OV | 企业型证书 | 最长 398 天 | 同上 | 支付回调、金融、政企验收 |
| EV | 增强型证书 | 最长 398 天 | 同上 | 浏览器地址栏展示企业名(H5 落地页) |
通配符有两个坑:*.example.com 只覆盖一级子域,api.test.example.com 不在其中;而小程序后台配置服务器域名时不允许填通配符,必须写具体的 https://api.example.com。另外微信会严格比对域名与证书 CN/SAN,证书里没有 www 就不要在小程序里请求 www 前缀。
三、完整实操:生成 CSR、申请与安装证书
步骤 1:生成私钥与 CSR(-addext 需要 OpenSSL 1.1.1+,否则改用配置文件写 SAN):
mkdir -p /etc/nginx/ssl && cd /etc/nginx/ssl
openssl genrsa -out api.example.com.key 2048
openssl req -new -key api.example.com.key -out api.example.com.csr
-subj '/C=CN/ST=Guangdong/L=Shenzhen/O=YourCompany/CN=api.example.com'
-addext 'subjectAltName=DNS:api.example.com,DNS:www.example.com'
openssl req -in api.example.com.csr -noout -text | grep -A1 'Subject Alternative Name'
步骤 2:提交 CA 并完成域名验证,常见三种方式:DNS TXT 记录、HTTP 文件校验(/.well-known/pki-validation/)、管理员邮箱收信。OV/EV 还需提交营业执照并等待人工审核,通常 1 个工作日。
步骤 3:用 acme.sh 自动签发(推荐生产使用):
curl https://get.acme.sh | sh -s email=ops@example.com
~/.acme.sh/acme.sh --set-default-ca --server letsencrypt
~/.acme.sh/acme.sh --issue -d api.example.com -d www.example.com --webroot /var/www/html
# 通配符必须走 DNS-01,例如阿里云 DNS
~/.acme.sh/acme.sh --issue -d example.com -d '*.example.com' --dns dns_ali
~/.acme.sh/acme.sh --install-cert -d api.example.com
--key-file /etc/nginx/ssl/api.example.com.key
--fullchain-file /etc/nginx/ssl/api.example.com.fullchain.pem
--reloadcmd 'nginx -t && systemctl reload nginx'
关键点:必须用 --fullchain-file 而不是 --cert-file。只装服务器证书不带中间证书,是 Android 端 ssl hand shake error 最常见的原因。
步骤 4:校验证书与私钥是否匹配:
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in privkey.pem | openssl md5
两个 MD5 必须完全一致,否则 Nginx 启动时报 key values mismatch。
步骤 5:验证证书链完整性:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -E 'i:|s:'
正常输出应包含 1~2 个 i:(中间证书颁发者)加 1 个根证书提示;只有 1 个 s: 而没有 i:,说明链不完整。
四、配置示例:Nginx / Tomcat / Apache / IIS
Nginx(推荐,A 级评分配置):
server {
listen 443 ssl;
http2 on; # Nginx 1.25.1+ 写法;旧版用 listen 443 ssl http2;
server_name api.example.com www.example.com;
ssl_certificate /etc/nginx/ssl/api.example.com.fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/api.example.com.key;
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:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem;
add_header Strict-Transport-Security 'max-age=31536000' always;
location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; }
}
server {
listen 80;
server_name api.example.com www.example.com;
return 301 https://$host$request_uri;
}
Tomcat(9 / 10,PEM 直读,无需转 JKS):
<Connector port='443' protocol='org.apache.coyote.http11.Http11NioProtocol'
maxThreads='200' SSLEnabled='true' scheme='https' secure='true'>
<SSLHostConfig protocols='TLSv1.2,TLSv1.3'>
<Certificate certificateFile='/opt/tomcat/ssl/fullchain.pem'
certificateKeyFile='/opt/tomcat/ssl/privkey.pem'
type='RSA' />
</SSLHostConfig>
</Connector>
Apache httpd 2.4:
<VirtualHost *:443>
SSLEngine on
SSLCertificateFile /etc/httpd/ssl/fullchain.pem
SSLCertificateKeyFile /etc/httpd/ssl/privkey.pem
# 2.4.8 起 fullchain 已含中间证书,无需 SSLCertificateChainFile
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
Header always set Strict-Transport-Security 'max-age=31536000'
</VirtualHost>
IIS(PowerShell 导入 pfx 并绑定 443):
Import-PfxCertificate -FilePath C:sslapi.example.com.pfx `
-CertStoreLocation Cert:LocalMachineMy -Password (ConvertTo-SecureString 'PfxPwd' -AsPlainText -Force)
New-WebBinding -Name 'ApiSite' -Protocol https -Port 443 -HostHeader api.example.com -SslFlags 1
修改后务必先做语法校验再重载:nginx -t、apachectl configtest,Tomcat 需 systemctl restart tomcat。
五、对比表格:四种服务器配置差异与 A 级评分要点
| 项目 | Nginx | Apache httpd | Tomcat | IIS |
|---|---|---|---|---|
| 证书指令 | ssl_certificate / ssl_certificate_key | SSLCertificateFile / SSLCertificateKeyFile | <Certificate certificateFile certificateKeyFile> | 导入“个人”存储后绑定 443 |
| 证书格式 | PEM(fullchain) | PEM(fullchain) | PEM 或 PKCS12/JKS | .pfx(PKCS12) |
| 是否需单独配中间证书 | 否(fullchain 内含) | 2.4.8+ 否 | 否 | 否(pfx 内含) |
| TLS 版本开关 | ssl_protocols | SSLProtocol | SSLHostConfig protocols | Schannel 注册表 |
| 生效命令 | nginx -t && systemctl reload nginx | apachectl configtest && systemctl reload httpd | systemctl restart tomcat | iisreset |
| 热加载不断连接 | 支持(reload) | 支持(graceful) | 不支持,需重启 | 支持(回收应用池) |
要达到 SSL Labs / MySSL 的 A 级评分,逐项对照下表自查:
| 检查项 | 推荐值 | 不达标的后果 |
|---|---|---|
| TLS 版本 | TLSv1.2 + TLSv1.3 | 仍开 TLS 1.0/1.1 直接降到 B |
| 密钥交换 | ECDHE(X25519 / P-256) | 仅 RSA 密钥交换则无前向保密,降级 |
| 证书链 | 含中间证书 | Android 老机型握手失败 |
| OCSP Stapling | on,且配置 ssl_trusted_certificate | 首次握手多一次外网 RTT |
| HSTS | max-age=31536000 | 不影响评级,但降安全分 |
| 会话复用 | shared:SSL:10m | 高并发下握手 CPU 飙升 |
特别提醒:小程序客户端不解析 HSTS,但小程序内嵌 web-view 和 H5 落地页会解析。如果同一域名还要给其他不支持 HTTPS 的旧系统用,先不要加 includeSubDomains 和 preload,否则回滚很麻烦。
六、常见错误排查(含真实报错)
下面这些报错都来自真实工单,按出现频率排序:
| 报错信息 | 根因 | 处理 |
|---|---|---|
wx.request:fail ssl hand shake error |
证书链缺中间证书、协议版本过低、证书过期 | 改用 fullchain.pem;ssl_protocols TLSv1.2 TLSv1.3;openssl x509 -noout -dates 核对有效期 |
request:fail 此服务器的证书无效 |
自签名证书,或域名与 CN/SAN 不匹配 | 换公共 CA 证书;核对 SAN 是否含请求域名 |
nginx: [emerg] SSL_CTX_use_PrivateKey_file(...) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch) |
证书与私钥不配套(续签后只换了其中一个) | 用第三节的 modulus MD5 比对,成对替换 |
curl: (60) SSL certificate problem: unable to get local issuer certificate |
服务端只下发了服务器证书 | 拼接中间证书:cat server.crt intermediate.crt > fullchain.pem |
nginx: [emerg] cannot load certificate ... PEM_read_bio_X509_AUX() failed |
上传了 DER/CRT 二进制格式,或文件里混入网页文本、多余空行 | openssl x509 -in cert -inform DER -out cert.pem 转 PEM,去掉首尾杂字符 |
err: domain list 不在以下 request 合法域名列表中 |
小程序后台未配置该域名,或域名未备案、用了 IP 或非 443 端口 | 后台添加 https://api.example.com 后重新编译、重进体验版 |
java.security.cert.CertificateException: No name matching api.example.com found |
Tomcat 未启用 SNI,或多域名共用同一 Connector 但证书不含该域名 | 为每个域名单独配置 <SSLHostConfig hostName='...'> |
sslv3 alert handshake failure |
客户端仅支持 TLS 1.0/1.1,服务端已禁用 | 用 openssl s_client -tls1_1 复现确认;升级客户端 SDK 或临时放开 |
排查顺序建议固定为:先 openssl s_client 看协议与链 → 再 curl -vI 看 HTTP 层 → 最后查小程序后台域名配置与备案。90% 的“真机失败”都停在前两步。此外别忘了检查服务器系统时间:timedatectl 偏差超过 5 分钟,会直接导致 ERR_CERT_DATE_INVALID。
七、效果验证:命令行 + 真机三步确认
第一步,服务端自检:
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null
# 关注三项:Protocol 是否为 TLSv1.2/1.3;Cipher 是否 ECDHE 开头;verify return code 是否为 0 (ok)
curl -sSI https://api.example.com/health
curl -vI --tlsv1.2 https://api.example.com 2>&1 | grep -E 'SSL|subject|issuer|expire'
nmap --script ssl-enum-ciphers -p 443 api.example.com
第二步,链与有效期核对:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
~/.acme.sh/acme.sh --list # 查看续期时间
systemctl list-timers | grep acme # 确认续期定时器已生效
第三步,真机验证:上传体验版,在真机上打开 vConsole → Network 面板,观察请求的 status 与 TLS 信息。Android 与 iOS 各测一台,且尽量保留一台 Android 7 以下或 iOS 12 以下的老设备,因为老系统的根证书库最旧,链不完整、根证书过期这类问题只会在它们身上暴露。开发者工具关闭“不校验合法域名”选项后再跑一遍,可提前发现大部分问题。
最后用 MySSL 或 SSL Labs 做一次外部评级,目标 A 及以上;同时人为触发一次续期演练(acme.sh --renew --force),确认 reloadcmd 能正常拉起服务,避免 90 天后证书静默过期。
常见问题
小程序必须买付费证书吗?免费的 Let’s Encrypt 能用吗?
能用。微信只校验证书是否由受信任的公共 CA 签发、域名是否匹配、链是否完整,不区分 DV/OV/EV,也不看价格。Let’s Encrypt 已被主流 Android/iOS 信任,完全可以跑生产小程序。唯一代价是 90 天有效期必须做自动续期,建议用 acme.sh 的 --install-cert 配合 --reloadcmd 全自动处理,并加一条续期失败告警。
证书有效期到底是 398 天还是 1 年?旧文章说可以买 2 年、3 年?
公开信任的 TLS 证书目前最长有效期为 398 天,超过这个长度的证书会被主流浏览器直接拒绝。市面上所谓“2 年、3 年证书”,本质是签发 398 天证书并捆绑后续重签服务,仍需按周期更换。Let’s Encrypt 则固定 90 天。行业已确定分阶段继续缩短至 200 天、100 天、47 天,因此正确做法是把证书更新做成自动化流程,而不是按年采购。
为什么微信开发者工具里一切正常,真机却报 ssl hand shake error?
因为开发者工具默认勾选了“不校验合法域名、TLS 版本以及 HTTPS 证书”,而真机走微信客户端的严格校验。最常见三个原因:一是 Nginx 只配了 ssl_certificate 指向服务器证书而非 fullchain,缺中间证书;二是服务器仍开着 TLS 1.0/1.1 或禁用了 ECDHE;三是证书域名与请求域名不一致(如证书只有 api.example.com,请求却发了 www.api.example.com)。用 openssl s_client -showcerts 看链、用 -tls1_2 看协议即可定位。
小程序可以用 IP 地址或非 443 端口吗?
不可以。小程序后台的服务器域名只接受已备案的域名,且协议必须是 https:// 或 wss://,端口固定 443,不支持填写 IP、localhost、通配符域名或自定义端口。如果后端服务监听在 8080,必须在 Nginx 上做 443 反向代理转发,不能把 8080 直接填进小程序。
通配符证书能直接填到小程序服务器域名里吗?
不能。小程序后台配置域名时不支持通配符写法,必须逐个填写具体子域名,如 https://api.example.com。但通配符证书本身可以用在服务端:一张 *.example.com 证书可以覆盖 api.example.com、img.example.com,只要每个子域在小程序后台单独登记即可。注意通配符只覆盖一级子域,a.b.example.com 需要单独签发。
如何做到证书到期零中断?
三条同时做:一是用 acme.sh 或 certbot 的定时任务自动续期,并在 --reloadcmd 中执行 nginx -t && systemctl reload nginx,保证配置有误时不会把服务 reload 挂;二是加监控,对 443 端口做每日探测,解析 openssl s_client 输出的 notAfter,剩余天数少于 15 天告警;三是续期后做一次完整校验(modulus MD5 比对 + 真机回归),避免出现“证书换了、私钥没换”导致 key values mismatch 的低级事故。