跳到主要内容
ssl证书按装

微信小程序 HTTPS 证书申请与部署全流程:CSR 生成、Nginx/Tomcat 配置、真实报错排查与验证

微信小程序 HTTPS 证书申请与部署全流程:CSR 生成、Nginx/Tomcat 配置、真实报错排查与验证 — 微信小程序 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 的低级事故。

内容审核

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