跳到主要内容
ssl证书按装

微信小程序 HTTPS 证书申请、安装与配置全流程实战(Nginx/宝塔示例 + 真实报错排查)

微信小程序 HTTPS 证书申请、安装与配置全流程实战(Nginx/宝塔示例 + 真实报错排查) — 微信小程序 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、不能带端口。配置入口在微信公众平台开发管理 → 服务器域名,每月修改次数有限。开发阶段可在开发者工具勾选「不校验合法域名」临时绕过,但上线前必须配好。

内容审核

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