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

微信小程序 HTTPS 证书申请与 Nginx 配置全流程(含真实报错排查与验证)

微信小程序 HTTPS 证书申请与 Nginx 配置全流程(含真实报错排查与验证) — 微信小程序 HTTPS 证书申请与 Nginx 配置全流程(含真实报错排查与验证)

一、问题背景与根因:小程序为什么必须上 HTTPS

微信小程序的网络层是硬性约束:wx.request、wx.uploadFile、wx.downloadFile 只允许 https:// 请求,http 直接返回 request:fail。域名还必须在微信公众平台「开发管理 → 开发设置 → 服务器域名」里配置为 request 合法域名,且要求:已完成 ICP 备案、不能带端口(固定 443)、不能是 IP 地址、证书由受信任 CA 签发、TLS 版本不低于 1.2。很多团队以为「浏览器能打开就没问题」,结果真机报 request:fail ssl hand shake error,根因通常只有三类:

  • 证书链不完整:Nginx 只配了站点证书(leaf),没拼中间 CA,Android 微信能过、iOS 直接握手失败;
  • 域名不匹配:证书 SAN 里只有 www.example.com,而小程序请求的是裸域 example.com(这两个是不同的名字);
  • 协议或套件过旧:服务端仍开启 TLS 1.0/1.1,或只提供 RC4/3DES 套件,被微信客户端拒绝。

先跑两条命令定位,不要靠猜:

curl -sSI https://api.example.com/health
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -E 'Verify return code|subject=|issuer='

输出 Verify return code: 21 (unable to verify the first certificate) 说明缺中间证书;只有 Verify return code: 0 (ok) 才代表链完整。还有一条有效期红线:自 2020-09-01 起,公开信任的 TLS 证书单张最长有效期被限制为 398 天,Let’s Encrypt 更短,只有 90 天,靠手工续期必然踩到过期事故,必须做自动化。

二、证书类型与选型:DV / OV / EV、单域名、多域名与通配符

先看验证等级差异:DV 走 DNS TXT 或 HTTP 文件校验,10 分钟内签发;OV 需核验营业执照并做企业电话回拨,1~2 个工作日;EV 还要验证企业电话,座机、DUNS 记录、企业信用公示信息里的号码都可以用。小程序只校验「是否受信任 + 域名是否匹配 + TLS 版本」,DV 完全够用;OV/EV 更多用于对外展示主体身份。

类型 验证方式 签发时长 覆盖范围 适用场景
DV 单域名 DNS / 文件校验 约 10 分钟 1 个 FQDN 小程序 API 域名
DV 通配符 仅 DNS-01 约 10 分钟 *.example.com 一级子域 多子域统一管理
OV 单域名/通配符 企业资料 + 电话回拨 1~2 工作日 同 DV 对外展示企业身份
EV 企业电话核验 1~3 工作日 1 个 FQDN 金融、支付回调

域名覆盖是踩坑重灾区,务必按 SAN 字段核对:单域名只覆盖 1 个 FQDN,多数 CA 的「单域名」不会自动带上 www,购买时要确认是否同时含 www.example.com 与 example.com 两个 SAN;多域名证书(SAN/UCC)通常 3~5 个起售,可跨主域;通配符 *.example.com 只覆盖一级子域,api.example.com 和 www.example.com 可以,a.b.example.com 这类三级域名不支持。

三、生成私钥与 CSR:可直接执行的命令

签发前先在本机生成私钥与 CSR(证书签名请求),私钥绝不外传。推荐 2048 位 RSA 或 P-256 ECDSA:

# RSA 2048
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out example.com.key
# 或 ECDSA P-256,握手更快、更省 CPU
openssl ecparam -genkey -name prime256v1 -noout -out example.com.key

openssl req -new -key example.com.key -out example.com.csr 
  -subj '/C=CN/ST=Zhejiang/L=Hangzhou/O=Example Co.,Ltd/CN=example.com' 
  -addext 'subjectAltName=DNS:example.com,DNS:www.example.com'
chmod 600 example.com.key
openssl req -in example.com.csr -noout -text | grep -A1 'Subject Alternative Name'

关键点:CN 只写主域名,www 与裸域必须写进 subjectAltName,否则小程序请求哪个名字都可能报 ERR_CERT_COMMON_NAME_INVALID。拿到证书后先确认证书与私钥配对,再拼接完整链:

openssl x509 -noout -modulus -in example.com.crt | openssl md5
openssl rsa -noout -modulus -in example.com.key | openssl md5   # 两行一致才配对
openssl pkey -in example.com.key -pubout | openssl md5          # ECDSA 用这条
cat example.com.crt intermediate.crt > fullchain.pem

fullchain 的顺序是「站点证书 → 中间 CA」,不要放根证书,也不要放反,放反后 iOS 端会直接握手失败。

四、申请与自动续期:acme.sh 一条命令搞定

手工上传证书在 398 天(甚至 90 天)规则下不可持续,直接用 acme.sh 做 DNS-01 自动签发,通配符也能覆盖:

curl https://get.acme.sh | sh -s email=ops@example.com
source ~/.bashrc
# 以阿里云 DNS 为例,其他服务商换成 dns_dgon / dns_cf 等
 export Ali_Key='LTAIxxxx' Ali_Secret='xxxxxxxx'
~/.acme.sh/acme.sh --issue --dns dns_ali 
  -d example.com -d '*.example.com' --keylength ec-256
~/.acme.sh/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'

–install-cert 会把证书复制到指定路径并注册续期钩子;acme.sh 安装时已自动写入 crontab,每天检查、到期前 30 天续签。用 crontab -l | grep acme.sh 和 ~/.acme.sh/acme.sh –list 确认任务与 Next renew 时间。Let’s Encrypt 有效期 90 天,续期后必须 reload Nginx 才生效,–reloadcmd 就是干这个的。用 HTTP-01 也可以:acme.sh –issue -d example.com -w /var/www/html,但通配符只能用 DNS-01。若用 Certbot:certbot certonly –webroot -w /var/www/html -d example.com -d www.example.com,续期靠 systemctl enable –now certbot.timer。

五、Nginx 配置示例:TLS 1.2/1.3 + 完整链 + HSTS

server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}
server {
    listen 443 ssl;
    http2 on;
    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_trusted_certificate /etc/nginx/ssl/example.com.chain.pem;

    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';
    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;
    resolver 223.5.5.5 119.29.29.29 valid=300s;

    add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;

    location /health { return 200 'ok'; }
}

要点:ssl_certificate 必须指向 fullchain(站点证书 + 中间 CA),这是小程序握手失败的头号原因;http2 on 是 Nginx 1.25.1+ 的写法,老版本用 listen 443 ssl http2;。改完先 nginx -t 再 systemctl reload nginx。若前面有 CDN 或 SLB,证书要在 CDN 侧也上传一份并把回源协议设为 HTTPS,否则源站证书再正确,客户端看到的仍是 CDN 上的旧证书。

六、方案对比:类型、覆盖范围与成本

方案 覆盖域名 验证方式 签发时长 单张有效期 参考年价(元)
DV 单域名(含 www) example.com + www DNS / 文件 约 10 分钟 398 天 0~300
DV 通配符 *.example.com(一级) 仅 DNS-01 约 10 分钟 398 天 400~1500
OV 单域名 1 个 FQDN 企业资料 + 回拨 1~2 工作日 398 天 800~2500
OV 通配符 *.example.com 企业资料 + 回拨 1~2 工作日 398 天 3000~8000
EV 单域名 1 个 FQDN 企业电话核验 1~3 工作日 398 天 2000~6000
多域名 SAN(3~5 个起) 多个 FQDN,可跨主域 同 DV / OV 视类型 398 天 按域名数加价

选型三条经验:①小程序后端域名固定(如 api.example.com),一张 DV 单域名证书即可,成本最低;②同一主域下还有 H5、管理后台、静态资源多个子域,直接上 DV 通配符,避免逐个续期;③需要向用户或合作方展示企业身份(金融、医疗、支付回调)再考虑 OV/EV。价格随 CA 与渠道浮动较大,表中为市场常见区间,以实际报价为准;免费证书(Let’s Encrypt、ZeroSSL)与付费 DV 在微信客户端眼中没有区别,只校验信任链、域名匹配与 TLS 版本。

还有两个成本陷阱:一是「单域名」通常不含 www,需要 www 与裸域同时可用时要买含两个 SAN 的套餐或多域名证书;二是多域名证书按域名数加价,扩到第 5 个域名时往往不如直接换通配符。续期周期上,公开信任证书单张最长 398 天,Let’s Encrypt 为 90 天,二者都必须自动化。

七、常见错误排查:真实报错与修复

报错 根因 修复
request:fail ssl hand shake error 缺中间证书 / 仅支持 TLS 1.0 / 服务器时间偏差 换成 fullchain、开启 TLS 1.2、校时
request:fail url not in domain list 域名未在公众平台配置,或带端口/IP 配置 request 合法域名,使用 443
curl: (60) SSL certificate problem: unable to get local issuer certificate 证书链不完整 ssl_certificate 指向 fullchain.pem
nginx: [emerg] PEM_read_bio_X509_AUX() failed … wrong tag 证书文件混入私钥或 PKCS#12 openssl pkcs12 -in a.pfx -nodes 拆出 cert 与 key
nginx: [emerg] SSL_CTX_use_PrivateKey_file() failed … key values mismatch 证书与私钥不配对 用 modulus / pubout 比对后重签
nginx: [warn] ssl_stapling ignored, issuer certificate not found 未配置 ssl_trusted_certificate 补上 chain.pem
ERR_CERT_COMMON_NAME_INVALID SAN 不含请求的域名 重签含 www 与裸域的证书

三条命令快速定位:

openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted chain.pem example.com.crt
date -u   # 与证书 Not Before / Not After 比对,偏差超 5 分钟必失败

还有一个易忽略点:开发者工具里的「不校验合法域名」开关只影响模拟器,真机不生效,勾选后能跑通不代表真机能跑通,务必用真机 + 体验版复测。另外 CDN 上证书已过期但源站正常,也是「本地 curl 正常、小程序报错」的常见原因。

八、效果验证:五条命令确认上线成功

# 1. 协议与套件
openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null 2>/dev/null | grep -E 'Protocol|Cipher|Verify return code'
# 2. 拒绝 TLS 1.0,应握手失败
openssl s_client -connect example.com:443 -servername example.com -tls1 </dev/null
# 3. 到期时间
 echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -dates -subject
# 4. 完整链校验
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted chain.pem example.com.crt
# 5. 实际请求
curl -sSI https://example.com/health | head -n 3

预期结果:Protocol 为 TLSv1.2 或 TLSv1.3、Verify return code: 0 (ok)、第 4 条输出 example.com.crt: OK、第 2 条返回 handshake failure 或 protocol version。再用微信开发者工具「真机调试」发一次 wx.request,控制台没有 ssl 相关 fail 即通过。上线后补一条到期监控:解析 notAfter 后接入告警,阈值设 15 天,与 acme.sh 的每日 cron 形成双保险。最后在 SSL Labs 跑一次评级,目标 A 及以上,重点确认 Certificate Chain 与 Protocol Support 两项全绿。

常见问题

是。微信公众平台配置的 request、uploadFile、downloadFile 合法域名不允许带端口号,实际走 443;域名还必须完成 ICP 备案、不能是 IP 地址,服务端需支持 TLS 1.2 及以上。非标端口的服务要用 Nginx 在 443 上做反向代理。


能。微信只校验证书是否由受信任 CA 签发、域名是否匹配、TLS 版本是否达标,与付费或免费无关。但 Let’s Encrypt 有效期只有 90 天,必须用 acme.sh 或 Certbot 自动续期并 reload Nginx,否则到期当天小程序全部请求失败。


不能。*.example.com 只匹配一级子域,如 api.example.com、www.example.com;a.b.example.com 这类三级域名不在覆盖范围内。确有三级域名需求时,需为其单独加 SAN 或单独签发一张证书。


自 2020-09-01 起,公开信任的 TLS 证书单张最长有效期为 398 天,Let’s Encrypt 等免费 CA 为 90 天。因此不要按「买多年省事」的思路规划,应把续期做成定时任务加到期告警。


依次排查:ssl_certificate 是否指向 fullchain(含中间 CA)、是否禁用 TLS 1.0/1.1、服务器时间是否偏差超过 5 分钟、CDN 或 SLB 上是否仍是旧证书。用 openssl s_client -connect 域名:443 -servername 域名 看 Verify return code 是否为 0。


可以,前提是这两个名字都写进证书的 SAN 字段。申请时在 CSR 里加 -addext ‘subjectAltName=DNS:example.com,DNS:www.example.com’,或购买标注「含 www」的单域名套餐;只写 CN 的旧式证书不保证覆盖裸域。

内容审核

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