微信小程序 HTTPS 证书申请、安装与配置全流程实战(Nginx/宝塔示例 + 真实报错排查)
一、问题背景:小程序 HTTPS 校验失败的三大根因
微信小程序要求所有网络请求必须走 HTTPS,且对 TLS 有硬门槛:协议版本不低于 TLS 1.2、证书由受信任 CA 签发、证书链完整、域名与证书 SAN 匹配。实际运维中绝大多数「小程序接口打不开」都能归到三类根因。
根因一:证书链不完整。只部署了域名证书(leaf),漏掉中间证书(intermediate)。桌面浏览器有时会自动补链,但 Android 微信、iOS 的 NSURLSession、Java HttpClient 不会,直接握手失败。根因二:协议或套件过旧。服务器仍开 TLS 1.0/1.1,或只配了 3DES、RC4 之类弱套件。根因三:域名不匹配或证书过期。证书只签了 example.com,请求却打到 api.example.com;或用了自签名证书;或证书已过期(公有 CA 单张证书有效期上限 398 天,Let’s Encrypt 固定 90 天)。
先做体检再动手,避免盲改配置:
# 查看服务端下发的证书链张数与有效期
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null | openssl x509 -noout -subject -issuer -dates
# 统计证书链张数,正常应 ≥ 2(域名证书 + 中间证书)
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null | grep -c 'BEGIN CERTIFICATE'
# 测试是否还开着 TLS 1.1(能握手成功说明需要关闭)
openssl s_client -connect api.example.com:443 -tls1_1 </dev/null
若输出出现 Verify return code: 21 (unable to verify the first certificate),基本可判定为缺中间证书。小程序端对应的报错通常是 request:fail ssl handshake error 或 errCode: -1,本质仍是上述三类问题。定位清楚后再进入申请与部署环节,可省掉大量来回试错。
二、申请前的准备:私钥与 CSR 的正确生成方式
CSR(Certificate Signing Request)决定证书里能装哪些域名,签错只能重签。关键点:CN 字段已不是主流 CA 的唯一校验依据,所有域名必须写进 SAN(subjectAltName),否则即使 CN 正确也会报域名不匹配。
推荐使用 ECC 私钥(P-256,握手更快、体积更小):
openssl ecparam -genkey -name prime256v1 -out api.example.com.key
openssl req -new -key api.example.com.key -out api.example.com.csr
-subj '/C=CN/ST=Guangdong/L=Shenzhen/O=YourCo/CN=api.example.com'
-addext 'subjectAltName=DNS:api.example.com,DNS:www.example.com'
若必须用 RSA(部分老旧客户端不支持 ECDSA),用 2048 位以上:
openssl genrsa -out api.example.com.key 2048
openssl req -new -sha256 -key api.example.com.key -out api.example.com.csr
-subj '/CN=api.example.com' -addext 'subjectAltName=DNS:api.example.com'
# 提交前务必校验 SAN 是否写全
openssl req -in api.example.com.csr -noout -text | grep -A2 'Subject Alternative Name'
私钥权限必须收紧:chmod 600 api.example.com.key,属主设为 Nginx 运行用户,否则部分 CA 会拒绝签发,也存在泄露风险。
类型选择:单域名证书只覆盖一个完全限定域名;通配符 *.example.com 只覆盖一级子域,不覆盖 example.com 主域本身,也不覆盖 a.b.example.com;多域名(SAN/UCC)证书默认 3~5 个域名,可付费扩容。有效期方面,自 2020-09-01 起公有 CA 签发的证书最长 398 天,Let’s Encrypt 为 90 天,因此续期自动化是必选项而非可选项。
三、域名验证与签发:HTTP-01 与 DNS-01 实操
DV 证书只需证明域名控制权,两种主流验证方式各有适用场景。
HTTP-01:CA 会访问 http://域名/.well-known/acme-challenge/<token>。宝塔面板的文件验证会把校验文件放在站点根目录的 .well-known/acme-challenge/ 下,但 Nginx 默认可能拦截点开头的目录,需要显式放行:
location ^~ /.well-known/acme-challenge/ {
root /www/wwwroot/api.example.com;
default_type text/plain;
}
DNS-01:添加 TXT 记录 _acme-challenge.example.com,适合通配符证书(通配符只能用 DNS-01)。验证生效:
dig +short TXT _acme-challenge.example.com
nslookup -type=TXT _acme-challenge.example.com 8.8.8.8
用 acme.sh 一条命令完成签发(以阿里云 DNS API 为例):
export Ali_Key=xxxxxxxx; export Ali_Secret=xxxxxxxx
acme.sh --issue --dns dns_ali -d example.com -d '*.example.com' --keylength ec-256
签发后拿到两个关键文件:私钥与 fullchain.cer(域名证书 + 中间证书)。部署时务必用 fullchain,而不是单独的 .cer 或 .crt。商业 CA 的压缩包通常含 domain.crt、ca_bundle.crt,合并顺序为「域名证书 → 中间证书」,顺序颠倒同样会握手失败:
cat domain.crt ca_bundle.crt > fullchain.pem
# 核对链中证书数量
awk 'BEGIN{c=0} /BEGIN CERT/{c++} END{print c}' fullchain.pem
四、Nginx 与宝塔面板配置示例
下面是一份可直接落地的最小可用配置,包含 80 跳转、TLS 1.2/1.3、现代加密套件与 HSTS:
server {
listen 80;
server_name api.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on; # Nginx 1.25.1+;旧版写 listen 443 ssl http2;
server_name api.example.com;
ssl_certificate /www/server/panel/vhost/cert/api.example.com/fullchain.pem;
ssl_certificate_key /www/server/panel/vhost/cert/api.example.com/privkey.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;
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto https;
}
}
宝塔面板路径:站点 → SSL → Let’s Encrypt 或「其他证书」,保存后写入 /www/server/panel/vhost/cert/<域名>/。最常见的坑是「证书夹」里只粘贴了域名证书,导致链不完整;正确做法是把中间证书内容拼接在域名证书之后一起粘贴。上传自有证书时,fullchain.pem 与 privkey.pem 必须成对,私钥不匹配会直接启动失败。
改完必须先做语法检查再平滑重载,切勿直接 reload 造成全站 502:
nginx -t && nginx -s reload
五、证书类型与部署方式对比
选型先看覆盖范围,再看运维成本。下表为常见证书类型对比:
| 类型 | 覆盖范围 | 验证方式 | 有效期上限 | 适用场景 |
|---|---|---|---|---|
| DV 单域名 | 1 个完全限定域名 | 域名/file 或 DNS | 398 天 | 单一 API 域名、测试环境 |
| DV 通配符 | *.example.com 一级子域 | 仅 DNS-01 | 398 天 | 子域多、批量部署 |
| 多域名 SAN | 3~5 个域名,可扩容 | 逐个域名验证 | 398 天 | 主域+多个业务域 |
| OV 企业型 | 单域名/多域名 | 企业实名核验 | 398 天 | 对外商务站点、合规要求 |
| Let’s Encrypt | 单域名/通配符 | HTTP-01 或 DNS-01 | 90 天 | 个人站、内部服务 |
部署方式对比,重点看「是否自动续期」:
| 方式 | 命令/入口 | 自动续期 | 注意事项 |
|---|---|---|---|
| 手动上传 | 面板粘贴 PEM | 否 | 需人工记录到期日,易漏 |
| 宝塔面板 | 站点 → SSL | 是(Let’s Encrypt) | 证书夹须拼完整链 |
| acme.sh | –issue –install-cert | 是(内置 cron) | 需配 –reloadcmd |
| certbot | certbot –nginx | 是(systemd timer) | 会改写 Nginx 配置 |
| CDN/WAF 托管 | 控制台上传 | 部分支持 | 源站与边缘须同步更新 |
选型结论:子域超过 3 个优先通配符 + DNS-01;有合规审计要求选 OV;纯内部服务用 Let’s Encrypt 配合 acme.sh 即可,但必须保证 90 天续期链路可用,否则会出现「凌晨批量过期」事故。
六、常见错误排查(附真实报错)
以下为部署 HTTPS 时出现频率最高的报错及对应处置:
| 报错信息 | 根因 | 处置 |
|---|---|---|
| verify error:num=21:unable to verify the first certificate | 只下发域名证书,缺中间证书 | 改用 fullchain.pem 部署 |
| curl: (60) SSL certificate problem: unable to get local issuer certificate | 链不完整或客户端 CA 库过旧 | 补全链;升级 ca-certificates |
| SSL_ERROR_RX_RECORD_TOO_LONG | 443 端口跑的是 HTTP 服务,或 80 端口误配 ssl | 检查 listen 指令与后端协议 |
| nginx: [emerg] cannot load certificate … PEM_read_bio_X509_AUX() failed | 文件路径错、内容为 CSR、或含多余文本 | 用 openssl x509 -in 验证文件可解析 |
| NET::ERR_CERT_COMMON_NAME_INVALID | SAN 未包含当前访问域名 | 重新签发并写入全部域名 |
| request:fail ssl handshake error(小程序) | TLS 版本过低或链不全 | 关闭 TLS 1.0/1.1,补全中间证书 |
| x509: certificate has expired or is not yet valid | 服务器时间不同步 | chronyc makestep 或 ntpdate 校时 |
两个高频细节:其一,nginx -t 通过不代表证书正确,务必用 openssl x509 -in fullchain.pem -noout -subject -dates 确认主体与有效期;其二,证书更换后 CDN、SLB、WAF 上的副本不会自动同步,边缘节点仍是旧证书时会表现为「部分用户报错、部分正常」,排查时应对边缘 IP 直接执行 openssl s_client -connect <边缘IP>:443 -servername 域名 对比指纹。
# 对比源站与边缘证书指纹是否一致
openssl s_client -connect api.example.com:443 -servername api.example.com /dev/null | openssl x509 -noout -fingerprint -sha256
七、自动化续期与到期监控
398 天与 90 天的有效期决定了续期必须自动化。acme.sh 安装证书时指定 reloadcmd,续期后自动重载服务:
acme.sh --install-cert -d example.com --ecc
--key-file /www/server/panel/vhost/cert/api.example.com/privkey.pem
--fullchain-file /www/server/panel/vhost/cert/api.example.com/fullchain.pem
--reloadcmd 'nginx -t && nginx -s reload'
# 确认 cron 已写入(默认每日 00:00 检查,到期前 30 天自动续签)
crontab -l | grep acme
acme.sh --list
certbot 用户先做一次演练,确认续期链路可用:
certbot renew --dry-run
systemctl list-timers | grep certbot
再补一层到期监控,把剩余天数打到监控系统或钉钉告警。下面脚本剩余不足 30 天返回非 0,可直接接入 Zabbix/Prometheus textfile:
#!/bin/bash
DOMAIN=api.example.com
END=$(echo | openssl s_client -connect $DOMAIN:443 -servername $DOMAIN 2>/dev/null
| openssl x509 -noout -enddate | cut -d= -f2)
LEFT=$(( ( $(date -d "$END" +%s) - $(date +%s) ) / 86400 ))
echo "ssl_cert_days_left{domain="$DOMAIN"} $LEFT"
[ $LEFT -lt 30 ] && exit 1 || exit 0
建议同时开启证书透明度(CT)日志订阅或 CA 到期邮件提醒,形成「自动续期 + 主动告警」双保险。
八、部署后的效果验证
配置完成不等于生效,按以下四层验证逐项打勾。
第一层,协议与套件。确认 TLS 1.0/1.1 已被拒绝,1.2/1.3 可握手:
openssl s_client -connect api.example.com:443 -tls1_1 </dev/null # 期望失败
openssl s_client -connect api.example.com:443 -tls1_3 </dev/null # 期望成功
openssl s_client -connect api.example.com:443 -servername api.example.com /dev/null | grep 'Protocol|Cipher'
第二层,证书链与主体。链张数 ≥ 2、SAN 含全部业务域名、剩余有效期大于 30 天:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName
第三层,HTTP 层。80 端口必须 301 到 443,HSTS 头存在,且无混合内容:
curl -I http://api.example.com
curl -sI https://api.example.com | grep -i 'strict-transport-security'
curl -s https://api.example.com | grep -o 'http://[^"]*' | head
第四层,客户端真机。微信开发者工具默认不校验域名,会掩盖问题,必须用真机 + 关闭「不校验合法域名」选项测试;同时在 https://myssl.com 或 SSL Labs 跑一次评级,目标 A 级以上、无弱套件告警。最后在微信公众平台「开发管理 → 服务器域名」确认 request 合法域名已填写且备案通过,域名不能带端口、不能是 IP。
常见问题
多半是证书链不完整或 TLS 版本过低。用 openssl s_client -connect 域名:443 -showcerts 查看返回证书张数,正常应至少 2 张;再用 -tls1_1 测试,能握手说明旧协议未关闭。修复后执行 nginx -t && nginx -s reload,并用真机重测。
*.example.com 只覆盖一级子域,如 api.example.com、www.example.com,数量不限;但不覆盖主域 example.com 本身,也不覆盖 a.b.example.com。需同时覆盖主域时,签发时把 example.com 与 *.example.com 一并写入 SAN,或改用多域名证书。
目前公有 CA 签发的证书单张有效期上限为 398 天(2020-09-01 起生效),Let’s Encrypt 免费证书固定 90 天。缩短有效期是为降低私钥泄露风险、推动自动化续期,因此必须配置 acme.sh 或 certbot 定时任务,并设置到期前 30 天告警。
这类客户端不会自动补全证书链,只认服务端下发的完整链。检查是否只部署了域名证书而漏掉中间证书,把 ca_bundle 拼接进 fullchain 后重载;同时确认 SNI 已开启,老版本 HttpClient 还需将根证书显式导入 truststore。
不需要重启,执行 nginx -t 校验配置后 nginx -s reload 即可平滑加载新证书。使用 acme.sh 时可在 –install-cert 加 –reloadcmd 让续期后自动生效。注意 CDN、SLB、WAF 上的证书副本需同步更新,否则边缘节点仍是旧证书。
必须。小程序 request 合法域名要求已备案、必须 HTTPS、不能使用 IP、不能带端口。配置入口在微信公众平台开发管理 → 服务器域名,每月修改次数有限。开发阶段可在开发者工具勾选「不校验合法域名」临时绕过,但上线前必须配好。