微信小程序 HTTPS 部署实战:泛域名 SSL 证书申请、Nginx 配置与排错全流程
一、问题背景与根因:小程序为什么“非 HTTPS 不可”
微信小程序对网络请求的限制是硬性的:wx.request、wx.uploadFile、wx.downloadFile、wx.connectSocket 只允许访问已在“服务器域名”白名单中登记的 HTTPS / WSS 地址。域名必须完成 ICP 备案、不能是 IP、不能带端口(固定 443),证书必须由受信任 CA 签发且证书链完整。微信客户端在 Android 与 iOS 上都要求 TLS 1.2 及以上,iOS 的 ATS 还额外要求 SHA-256 签名、RSA 密钥 ≥ 2048 位或 ECC ≥ 256 位。
实践中,导致小程序无法访问 API 的主要原因通常在于三件事,证书本身并不是主要问题。第一,证书覆盖范围不够:小程序往往同时调用 api.example.com、img.example.com、ws.example.com,如果使用单域名证书,就要购买多张证书并在多个站点分别部署;而泛域名证书 *.example.com 用一张即可覆盖所有一级子域名。第二,证书链不完整:服务器只发送了站点证书,没有发送中间证书,浏览器能够自动补全证书链,但微信内置的 OkHttp 会直接握手失败。第三,服务器 TLS 版本或加密套件过旧,被客户端拒绝。
原文中关于 Windows 的限制需要更新:IIS 6(Windows Server 2003)与 IIS 7(Windows Server 2008)不支持 SNI,只能在同一个 IP:443 上绑定一张证书;从 IIS 8(Windows Server 2012)起支持 SNI,可以在同一 IP:443 上为多个站点分别绑定不同证书。这两个系统均已停止支持,不应再用于对外提供 HTTPS 服务。Linux 侧 Apache 2.2.12+ 已支持 SNI,Nginx 全系支持,所谓“Apache 只能配一个证书”的说法早已过时。
还有一个必须纠正的过时事实:自 2020-09-01 起,公开信任的 TLS/SSL 证书最长有效期被限制为 398 天;Let’s Encrypt 免费证书为 90 天。CA/B Forum 已通过 SC-081 决议,将分阶段缩短为:2026-03-15 起 200 天、2027-03-15 起 100 天、2029-03-15 起 47 天。这意味着“一次部署管三年”的做法彻底不可行,自动化续期是必选项而非加分项。
二、证书选型:泛域名、单域名与多域名 SAN 的差异
泛域名证书(Wildcard)只匹配“一级子域名”:*.example.com 覆盖 api.example.com,但不覆盖 example.com(裸域)和 a.b.example.com(二级子域)。因此下单时必须同时勾选裸域,最终证书的 SAN 为 DNS:*.example.com, DNS:example.com。这是小程序部署里“证书明明买了却报域名不匹配”的最常见原因。
| 证书类型 | 覆盖范围 | 典型年费 | 适用场景 | 关键限制 |
|---|---|---|---|---|
| 单域名 DV | 1 个 FQDN | 免费 ~ 300 元 | 只有一个接口域名 | 每新增子域名都要重签 |
| 泛域名 DV | *.example.com + 裸域 | 800 ~ 3000 元 | 子域名多、需弹性扩展 | 不覆盖二级子域;只能 DNS-01 验证 |
| 多域名 SAN | 最多 100 个 FQDN | 按域名数计价 | 跨主域名的多个域名 | 域名列表固定,增删需重签 |
| OV / EV | 单域名或泛域名 | 2000 元以上 | 金融、支付类业务 | 需企业资质审核;EV 已不再显示绿色地址栏 |
| Let’s Encrypt 泛域名 | *.example.com + 裸域 | 0 元 | 中小项目、测试环境 | 有效期仅 90 天,必须自动化续期 |
算法选择上:RSA 2048 兼容性最好;ECDSA P-256 证书体积小、握手更快,微信客户端(Android 5.0+ / iOS 9+)均支持,但老旧的抓包工具与 Java 6 环境可能不认,联调阶段建议先用 RSA。所有公开信任证书都受 398 天上限约束,泛域名证书也不例外,不存在“泛域名可以签三年”的情况。
三、实操第一步:生成私钥、CSR 与泛域名申请
私钥必须在服务器本地生成,绝不出机器。泛域名的 CSR 里 CN 填 *.example.com,SAN 同时写泛域名和裸域,否则签出来的证书不含裸域。
mkdir -p /etc/nginx/ssl && cd /etc/nginx/ssl
# 1. 生成 2048 位 RSA 私钥(如需 ECC:openssl ecparam -genkey -name prime256v1 -out example.com.key)
openssl genrsa -out example.com.key 2048
chmod 600 example.com.key
# 2. 生成 CSR(-addext 需要 OpenSSL 1.1.1 及以上)
openssl req -new -sha256 -key example.com.key -out example.com.csr
-subj "/C=CN/ST=Zhejiang/L=Hangzhou/O=Example Technology Co.,Ltd/CN=*.example.com"
-addext "subjectAltName=DNS:*.example.com,DNS:example.com"
# 3. 校验 CSR 内容,确认 SAN 两项都在
openssl req -in example.com.csr -noout -text | grep -A1 "Subject Alternative Name"
第二步是域名验证。按 CA/B Forum 规定,泛域名证书只能走 DNS-01 验证,需要在 _acme-challenge.example.com 添加 TXT 记录。商业 CA 会给出 TXT 值,手动添加后用 dig 确认全网生效再提交:
dig +short TXT _acme-challenge.example.com @8.8.8.8
# 期望输出形如:"随机字符串"
# 同时检查 CAA 记录是否限制为其他 CA
dig +short CAA example.com
第三步(推荐):用 acme.sh 自动签发与续期,通过 DNS API 免去手工添加 TXT。以阿里云 DNS 为例,Key/Secret 建议用 RAM 子账号并只授予 DNS 解析权限:
curl https://get.acme.sh | sh -s email=admin@example.com
export Ali_Key="LTAI5t******"
export Ali_Secret="******"
~/.acme.sh/acme.sh --issue --dns dns_ali
-d example.com -d '*.example.com' --keylength 2048
# 安装证书并配置续期后自动 reload
~/.acme.sh/acme.sh --install-cert -d example.com
--key-file /etc/nginx/ssl/example.com.key
--fullchain-file /etc/nginx/ssl/fullchain.cer
--reloadcmd "nginx -t && nginx -s reload"
注意 -d 必须写两次,一次裸域一次泛域名。DNS-01 验证不需要开放 80 端口,适合只暴露 443 的生产环境;签发完成后可用 openssl x509 -in fullchain.cer -noout -text | grep DNS 复核 SAN 列表。
四、Nginx 配置示例:证书链、TLS 版本与跳转
把商业 CA 提供的中间证书与站点证书按“站点证书在前、中间证书在后”拼接成 fullchain.cer,单独保留中间证书为 chain.pem 供 OCSP stapling 使用:
cat example.com.crt intermediate.crt > fullchain.cer
cat intermediate.crt > chain.pem
server {
listen 80;
server_name example.com *.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on; # nginx ≥ 1.25.1;旧版写 listen 443 ssl http2;
server_name example.com *.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.cer; # 必须含中间证书
ssl_certificate_key /etc/nginx/ssl/example.com.key;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem; # OCSP stapling 用
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;
resolver 223.5.5.5 119.29.29.29 valid=300s;
resolver_timeout 5s;
add_header Strict-Transport-Security "max-age=31536000" always;
add_header X-Content-Type-Options nosniff always;
root /data/www/example;
location / { try_files $uri $uri/ /index.html; }
}
三个必须注意的点:server_name *.example.com 只匹配一级子域,二级子域需要显式再加一条;fullchain.cer 的拼接顺序不能反,反了浏览器可能仍能打开,但微信会握手失败;小程序后台要求的校验文件(形如 MP_verify_xxxx.txt)必须能通过 HTTPS 直接访问且返回 200,不能被前端路由拦截。改完执行 nginx -t 再 nginx -s reload,切勿直接 reload。
五、小程序后台配置与端到端联调
服务器配置完成后,必须在小程序后台登记域名:微信公众平台 → 开发 → 开发管理 → 开发设置 → 服务器域名,分别填写 request 合法域名、uploadFile 合法域名、downloadFile 合法域名、socket 合法域名(wss)。规则是:必须是 https / wss、必须已备案、不能是 IP、不能带端口、不能是 localhost;每月修改次数有限(当前为 50 次),上线前一次配好。
用命令行模拟微信客户端做端到端校验,比在开发者工具里盲试高效得多:
# 模拟 TLS 1.2 握手并输出完整证书链(应看到至少 2 张证书)
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 -showcerts </dev/null
# 只看证书主题、有效期与 SAN
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null
| openssl x509 -noout -subject -dates -ext subjectAltName
# 验证证书链是否完整(返回 OK 才算通过)
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt
-untrusted /etc/nginx/ssl/chain.pem /etc/nginx/ssl/fullchain.cer
开发者工具里“详情 → 本地设置 → 不校验合法域名”只对开发环境生效,真机预览与体验版仍走严格校验,不能靠它掩盖证书问题。如果只有 Android 报错、iOS 正常,通常是证书链缺中间证书或服务端仍开放 TLS 1.0/1.1;反之只有 iOS 报错,多半是签名算法用了 SHA-1 或密钥长度不足 2048 位。
六、自动化续期:cron、systemd timer 与过期巡检
acme.sh 安装时会自动写入 cron 任务,用 crontab -l 确认存在:0 3 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null。若系统统一用 systemd 管理定时任务,可改用 timer,并加随机延迟避免多台机器同时打 DNS API:
# /etc/systemd/system/acme-renew.service
[Unit]
Description=Renew acme.sh certificates
[Service]
Type=oneshot
ExecStart=/root/.acme.sh/acme.sh --cron --home /root/.acme.sh
# /etc/systemd/system/acme-renew.timer
[Unit]
Description=Daily acme.sh renew
[Timer]
OnCalendar=*-*-* 03:17:00
RandomizedDelaySec=1800
Persistent=true
[Install]
WantedBy=timers.target
systemctl enable --now acme-renew.timer
续期成功不等于线上生效,必须写巡检脚本确认实际下发的证书在有效期内:
#!/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 "$DOMAIN 剩余 $LEFT 天"
[ "$LEFT" -lt 15 ] && echo "WARN: 证书即将过期" && exit 1
exit 0
acme.sh 默认在到期前 30 天续期(可用 --days 60 调整),--install-cert 时配置的 --reloadcmd 会被持久化,之后每次续期自动执行。如果改过 Nginx 证书路径,必须重新执行 install-cert,否则续期成功但线上仍是旧证书——这是“续期了但浏览器还显示过期”的头号原因。
七、常见错误排查:真实报错与定位命令
| 报错信息 | 根因 | 处理方式 |
|---|---|---|
request:fail ssl hand shake error(微信) |
证书链不完整、TLS 版本过低或域名不匹配 | openssl s_client -showcerts 确认返回 ≥2 张证书;确认 ssl_protocols 含 TLSv1.2 |
curl: (60) SSL certificate problem: unable to get local issuer certificate |
服务端未发送中间证书 | 把中间证书拼入 fullchain,站点证书在前 |
nginx: [emerg] SSL_CTX_use_PrivateKey_file(...) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch) |
私钥与证书不配对(常见于换证书没换 key) | 分别执行 openssl x509 -noout -modulus -in fullchain.cer | openssl md5 与 openssl rsa -noout -modulus -in example.com.key | openssl md5,两个值必须一致 |
nginx: [warn] "ssl_stapling" ignored, issuer certificate not found |
未配置 ssl_trusted_certificate 或 chain.pem 为空 |
补齐 chain.pem 并 reload |
400 Bad Request: The plain HTTP request was sent to HTTPS port |
CDN / 负载均衡回源协议配成了 HTTP | 回源改为 HTTPS 或源站同时监听 80 并跳转 |
ERR_TOO_MANY_REDIRECTS |
CDN 已做 HTTPS 跳转、源站又跳一次,或后端未识别 X-Forwarded-Proto |
后端加 proxy_set_header X-Forwarded-Proto $scheme;,全链路只保留一处跳转 |
x509: certificate has expired or is not yet valid |
证书确实过期,或服务器时钟漂移 | date -u 核对时间,用 chronyd / ntpdate 校时 |
net::ERR_CERT_COMMON_NAME_INVALID |
访问裸域 example.com 但证书只有 *.example.com |
重新签发并在 SAN 中加入裸域 |
排查顺序建议固定为:先用 openssl s_client -connect host:443 -servername host -showcerts 看链,再用 curl -vI https://host 看协议与响应头,最后看 Nginx error.log。微信后台保存域名时提示“域名不合法”,99% 是域名未备案、填了端口或写成了 http,逐项核对即可。
八、效果验证:命令化验收清单
# 1. 状态码与证书信息
curl -sI https://api.example.com/health | head -n 5
curl -sv https://api.example.com/health 2>&1 | grep -E "SSL connection|subject:|expire date|TLS"
# 2. 确认 TLS 1.0 / 1.1 已被拒绝(应返回 handshake failure)
openssl s_client -connect api.example.com:443 -tls1 </dev/null
openssl s_client -connect api.example.com:443 -tls1_1 </dev/null
# 3. 确认 TLS 1.3 可用
openssl s_client -connect api.example.com:443 -tls1_3 </dev/null | grep "Protocol"
# 4. 枚举支持的加密套件
nmap --script ssl-enum-ciphers -p 443 api.example.com
# 5. 第三方评级(目标 A 及以上)
curl -s "https://api.ssllabs.com/api/v3/analyze?host=api.example.com&publish=off&all=done" | head -c 800
验收清单逐项打勾:证书链 ≥ 2 张且顺序正确;有效期剩余 > 30 天;SAN 同时包含 *.example.com 与 example.com;TLS 1.0/1.1 已禁用、TLS 1.3 可用;HSTS 响应头存在;80 端口 301 跳转到 443;openssl verify 返回 OK;微信开发者工具与真机(Android + iOS 各一台)均能成功发起 wx.request。最后在小程序后台点一次“重新验证”或发布体验版复测,避免缓存导致的误判。
常见问题
不能。泛域名证书 *.example.com 只匹配一级子域名,不包含裸域本身。申请时必须在 SAN 中同时加入 DNS:example.com,acme.sh 命令行要写两次 -d:-d example.com -d '*.example.com',否则访问裸域会报证书名称不匹配。
不能。RFC 6125 规定通配符只匹配最左一段标签,*.example.com 只覆盖 api.example.com 这一级。若业务用到二级子域,需要单独签发 *.b.example.com,或把具体域名以 SAN 形式加入同一张证书。
先用 openssl s_client -connect 域名:443 -servername 域名 -showcerts 查看是否返回至少两张证书;只有一张说明缺中间证书。再确认服务端开启 TLS 1.2 及以上、证书未过期、域名在 SAN 列表中。三者任一不满足,微信内置网络库都会直接握手失败。
90 天,且泛域名只能通过 DNS-01 验证签发。90 天意味着必须自动化:用 acme.sh 的 DNS API 模式配合 cron 或 systemd timer 每 60 天续期一次,并配置 --reloadcmd 在续期后自动 reload Nginx,否则极易因忘记续期导致线上中断。
可以,同一张证书和私钥可部署到任意多台服务器或 CDN。但私钥副本越多泄露风险越大,建议私钥权限设为 600、仅 root 可读,禁止提交到 Git 仓库;多机部署时通过配置管理或密钥托管下发,并保留一份离线备份用于灾备恢复。
公开信任的 TLS 证书目前最长 398 天(2020-09-01 起生效)。CA/B Forum 已通过分阶段缩短方案:2026-03-15 起 200 天,2027-03-15 起 100 天,2029-03-15 起 47 天。因此无论商业证书还是免费证书,都必须把自动续期纳入运维流程。