小程序与网站 HTTPS 证书配置实战:Nginx SSL 部署、证书链修复与报错排查指南
一、问题背景与根因:小程序和网站为什么绕不开 HTTPS 证书配置
微信小程序从基础库 1.6.0 起,wx.request 与 wx.connectSocket 只允许 https:// 和 wss:// 请求,且服务端必须支持 TLS 1.2 及以上。开发阶段在微信开发者工具里勾选了「不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」时一切正常,一上真机就抛 request:fail ssl hand shake error——这是线上最高频的一类故障。
根因通常只有四类,九成集中在第一类:
1)证书链不完整。Nginx 的 ssl_certificate 只配了域名证书(叶子证书),没有把中间 CA 证书拼进去。桌面浏览器会自行补链,部分 Android 版本也会,但 iOS 与小程序真机严格校验,直接握手失败。2)TLS 协议版本过低。仍配置 ssl_protocols TLSv1 TLSv1.1;,协商不到 TLS 1.2。3)域名不匹配。证书 SAN 里没有 api.example.com,或误以为通配符 *.example.com 能覆盖 a.b.example.com(通配符只匹配一级)。4)证书过期。自 2020 年 9 月 1 日起,公有信任 CA 签发的 SSL/TLS 证书最长有效期被限制为 398 天;Let’s Encrypt 免费证书有效期为 90 天。忘记续期,就会在某天凌晨集体失效。
动手前先跑一条命令定位故障层级,看服务器到底发了什么:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null
| openssl x509 -noout -subject -issuer -dates
如果输出中 issuer 是中间 CA 名称、subject 是你的域名,且整段只出现一个 -----BEGIN CERTIFICATE-----,说明服务器只发了叶子证书,证书链缺失。再用 -tls1_2 单独测试一次,可确认协议支持情况:能连通说明协议没问题,连不上就是 ssl_protocols 或加密套件配置有误。
二、证书选型与 CSR 申请:单域名、通配符与 398 天有效期规则
小程序后端场景对证书等级要求不高,DV(域名验证型)证书足够,微信不校验 OV/EV。真正需要判断的是覆盖范围:
- 单域名证书:只保护
api.example.com,一个证书对应一个 FQDN。 - 通配符证书:
*.example.com覆盖api.example.com、www.example.com等一级子域,不覆盖裸域example.com,也不覆盖a.b.example.com。裸域必须在 SAN 里额外添加。 - 多域名(SAN/UCC)证书:一张证书挂多个不同主域,适合微服务共用入口。
生成 CSR 与私钥(RSA 2048 兼容性最好,ECDSA P-256 握手更快、证书体积更小):
# RSA 2048,同时写入 SAN,避免浏览器报域名不匹配
openssl req -new -newkey rsa:2048 -nodes
-keyout example.com.key -out example.com.csr
-subj "/C=CN/O=Example/CN=api.example.com"
-addext "subjectAltName=DNS:api.example.com,DNS:example.com,DNS:www.example.com"
# ECDSA P-256
openssl ecparam -genkey -name prime256v1 -out example.com.ec.key
openssl req -new -key example.com.ec.key -out example.com.ec.csr -subj "/CN=api.example.com"
申请时 CA 会要求验证域名归属:DNS 验证需添加 TXT 记录,文件验证需在网站根目录放置指定文件。若走免费路线,用 acme.sh 或 certbot 申请 Let’s Encrypt 证书,90 天有效期配合自动续期即可长期使用。注意:市面上所谓「2 年证书」在 398 天规则下已不可能由单张证书实现,实质是多年期订阅 + 多张证书自动轮换,采购时要确认服务商是否提供自动重签与自动部署,否则第二年仍需人工介入。
三、Nginx SSL 配置完整实操:从模块确认到 reload
第一步确认 Nginx 是否编译了 SSL 模块,没有输出就必须先解决依赖:
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'http_ssl_module|http_v2_module'
Debian/Ubuntu 可直接 apt install nginx-full;自编译需加 --with-http_ssl_module --with-http_v2_module --with-http_stub_status_module 重新编译。
第二步建立专用目录并收紧权限,私钥绝不能全局可读:
mkdir -p /etc/nginx/ssl && chmod 700 /etc/nginx/ssl
# 上传 example.com.key / example.com.crt / intermediate.crt 后
cat example.com.crt intermediate.crt > /etc/nginx/ssl/fullchain.crt
cp intermediate.crt /etc/nginx/ssl/chain.crt
chmod 600 /etc/nginx/ssl/example.com.key
chown root:root /etc/nginx/ssl/*
openssl x509 -in /etc/nginx/ssl/fullchain.crt -noout -dates -subject
第三步校验私钥与证书是否配对,不匹配时 reload 会直接失败:
openssl x509 -noout -modulus -in /etc/nginx/ssl/fullchain.crt | openssl md5
openssl rsa -noout -modulus -in /etc/nginx/ssl/example.com.key | openssl md5
两行 MD5 必须一致。第四步放行端口,云服务器要同时改安全组和本机防火墙:
firewall-cmd --permanent --add-service=https && firewall-cmd --reload
# 或 ufw allow 443/tcp
第五步灰度生效,避免直接 restart 打断长连接:
nginx -t && systemctl reload nginx && systemctl status nginx --no-pager
小程序的 request 合法域名不支持端口号、不支持 IP、必须 HTTPS,配置完成后记得回到微信公众平台「开发管理 → 服务器域名」同步填写。
四、Nginx 配置示例:HTTP 强制跳转 + TLS 1.2/1.3 + HSTS
下面是一份可直接落地的 /etc/nginx/conf.d/api.conf,包含 80 跳 443、TLS 1.2/1.3、会话复用、OCSP Stapling 与 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 /etc/nginx/ssl/fullchain.crt; # 叶子+中间证书
ssl_certificate_key /etc/nginx/ssl/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.crt;
resolver 223.5.5.5 119.29.29.29 valid=300s;
add_header Strict-Transport-Security "max-age=31536000" always;
add_header X-Content-Type-Options nosniff always;
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
几个容易踩坑的参数:ssl_prefer_server_ciphers 在 TLS 1.3 下已无效,保持 off 让客户端选择更快套件;ssl_stapling 必须配合 ssl_trusted_certificate 指向中间证书(不是 fullchain)才能生效,且需要 resolver 能解析 CA 的 OCSP 地址;HSTS 的 max-age 一旦下发,浏览器在有效期内拒绝走 HTTP,首次上线建议先用 max-age=300 观察一天再拉长到一年。小程序端只要求 TLS 1.2+,不要为了兼容老旧 Android 4.x 而放开 TLS 1.0,微信本身已不支持。
五、证书链合并与校验:fullchain 到底怎么拼
SSL 证书是三级结构:根证书(Root CA)→ 中间证书(Intermediate CA)→ 服务器证书(叶子)。根证书内置在操作系统与浏览器信任库中,服务器只需发送叶子证书 + 中间证书,顺序不能颠倒,也不要把根证书打包进去(会增大握手包,个别客户端还会告警)。
# 正确顺序:叶子在前,中间在后
cat example.com.crt intermediate.crt > fullchain.crt
# 本地验证链是否完整
openssl verify -untrusted intermediate.crt example.com.crt
# 期望输出:example.com.crt: OK
# 拆分 fullchain 检查每一段的身份
awk 'BEGIN{n=0} /BEGIN CERT/{n++} {print > "cert"n".pem"}' fullchain.crt
openssl x509 -in cert1.pem -noout -subject # 应为你的域名
openssl x509 -in cert2.pem -noout -subject # 应为中间 CA
部署后必须从外部验证服务器实际发送的链,而不是本地文件:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null
| grep -E '^ *[is]:|Verify return code'
健康输出应包含两段 i:(颁发者)与 s:(主体)记录,且末尾为 Verify return code: 0 (ok)。若出现 verify error:num=21:unable to verify the first certificate 或 Verify return code: 21,就是典型的中间证书缺失。另一个常见坑:从 CA 后台下载的是 .crt 与 .ca-bundle 两个文件,很多人只上传了前者;也有服务商把中间证书藏在压缩包的 chain/ 目录里,务必核对。若使用 ECDSA 证书,中间证书也要用对应的 ECDSA 链,RSA 与 ECDSA 双证书可通过 ssl_certificate 配置两次实现双栈。
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- SSL域名证书申请 · 小程序证书 · 国外SSL证书
- HTTPS证书申请 · SSL证书安装部署 · 证书续费
六、对比表格:证书类型、部署方式与配置项取舍
先看证书与配置服务的选型对照(价格为常见服务参考价,证书本身价格随 CA 与渠道浮动):
| 方案 | 覆盖范围 | 有效期 | 参考价格 | 适用场景 |
|---|---|---|---|---|
| 已有证书,仅配置服务 | 按原证书 | 按原证书 | 100 元 | 证书已购,缺 Nginx 部署与调优 |
| 单域名证书 + 配置 | 1 个 FQDN | ≤398 天 | 200 元 | 单一 API 域名 |
| 泛域名通配符证书 + 配置 | *.example.com 一级子域 | ≤398 天 | 600 元 | 多子域、多环境共用 |
| 单域名 2 年订阅 + 配置 | 1 个 FQDN | 2 张证书轮换 | 500 元 | 希望减少续期操作 |
| 泛域名 2 年订阅 + 配置 | *.example.com | 2 张证书轮换 | 1000 元 | 长期多子域业务 |
部署方式对比:
| 方式 | 续期 | 运维成本 | 风险点 |
|---|---|---|---|
| 手动上传证书 | 人工,398 天/90 天一次 | 低但易遗忘 | 过期事故、文件拼错 |
| certbot(webroot/dns 插件) | 自动,90 天续期 | 中 | 需配 hook 自动 reload |
| acme.sh + DNS API | 全自动,含通配符 | 低 | DNS API 密钥需妥善保管 |
关键配置项取舍:TLSv1.2 + TLSv1.3 是当前唯一推荐组合;RSA 2048 兼容性最好,ECDSA P-256 在移动弱网下握手更快,二者可共存;HSTS 建议先短 max-age 灰度;ssl_session_tickets off 更安全但会略微增加握手开销,会话缓存已能覆盖大部分场景。
七、常见错误排查:6 个真实报错与修复命令
报错 1:nginx: [emerg] PEM_read_bio_X509_AUX("/etc/nginx/ssl/fullchain.crt") failed (SSL: error:0480006C:PEM routines::no start line:Expecting: TRUSTED CERTIFICATE)。原因是文件为空、被上传工具截断,或下载的是 DER 格式。执行 file fullchain.crt,若显示 data 而非 ASCII text,用 openssl x509 -inform DER -in fullchain.crt -out fullchain.pem 转换。
报错 2:nginx: [emerg] SSL_CTX_use_PrivateKey_file("...key") failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)。证书与私钥不配对。用第三节的 modulus | md5 对比两行输出;ECDSA 证书改用 openssl ec -in key -pubout | md5 与 openssl x509 -in crt -pubkey -noout | md5 对比。不一致只能重新签发,无法修复。
报错 3:curl: (60) SSL certificate problem: unable to get local issuer certificate。客户端拿不到中间证书,即证书链不完整,按第五节重新合并 fullchain 并 reload。
报错 4:小程序真机 request:fail ssl hand shake error。先 openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2,握手失败说明 ssl_protocols 缺 TLSv1.2 或 ssl_ciphers 只保留了 TLS 1.3 套件;握手成功但仍报错,多为证书链或域名不匹配。
报错 5:curl: (60) SSL certificate problem: certificate has expired。证书已过期但 Nginx 仍加载旧文件——续期脚本只换了文件没 reload。执行 systemctl reload nginx,并把 --deploy-hook "systemctl reload nginx" 写进续期任务。
报错 6:浏览器 NET::ERR_CERT_COMMON_NAME_INVALID 或小程序 request:fail url not in domain list。前者是 SAN 不含当前域名(检查 openssl x509 -in fullchain.crt -noout -text | grep -A1 "Subject Alternative Name"),后者是微信公众平台未登记该域名,或域名带了端口/是 IP。
八、效果验证:命令行检测、在线评分与自动续期巡检
先用 curl 做一次端到端验证,ssl_verify_result 为 0 才代表证书校验通过:
curl -sS -o /dev/null -w "http_code=%{http_code} verify=%{ssl_verify_result} handshake=%{time_appconnect}sn" https://api.example.com/
# 期望:http_code=200 verify=0 handshake=0.0xxxs
再确认协议与套件:
echo | openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 2>/dev/null
| grep -E 'Protocol|Cipher|Verify return code'
# 期望:Protocol: TLSv1.2 / Cipher: ECDHE-RSA-AES128-GCM-SHA256 / Verify return code: 0 (ok)
在线评分可调用 SSL Labs API,目标 A 级及以上:
curl -s "https://api.ssllabs.com/api/v3/analyze?host=api.example.com&publish=off&all=done"
| jq -r '.endpoints[0].grade, .endpoints[0].details.protocols[].name'
最后加一条过期巡检脚本,挂到 cron 每日执行,把「证书到期」从事故变成提醒:
#!/usr/bin/env 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 ))
[ "$LEFT" -lt 15 ] && echo "$DOMAIN 证书剩余 ${LEFT} 天" | mail -s "SSL 到期告警" ops@example.com
小程序侧验证:关闭开发者工具「不校验合法域名」开关,用真机预览调用一次接口;确认公众平台「服务器域名」中的 request 域名与证书 SAN 完全一致,且不带端口。iOS 与 Android 各测一台,两端都通过才算真正完成 HTTPS 配置。
常见问题
证书只配了域名证书,为什么电脑浏览器正常、小程序真机却握手失败?
桌面浏览器内置了中间 CA 证书,能自行补全证书链;iOS 与小程序真机不做这种补全,只认服务器发来的完整链。把叶子证书与中间证书按「叶子在前、中间在后」合并成 fullchain 后写入 ssl_certificate,再用 openssl s_client -showcerts 确认返回 Verify return code: 0 (ok) 即可解决。
现在还能买到 2 年有效期的 SSL 证书吗?
不能。自 2020 年 9 月 1 日起,公有信任 CA 签发的 SSL/TLS 证书最长有效期被限制为 398 天,Let’s Encrypt 为 90 天。市面上的「2 年证书」实质是多年期订阅,服务商会在首张证书到期前自动重签并重新部署。采购时务必确认是否包含自动重签与自动 reload,否则第二年仍需人工操作。
通配符证书 *.example.com 能覆盖 api.example.com 和 example.com 吗?
能覆盖 api.example.com,但不能覆盖裸域 example.com,也不能覆盖二级子域 a.b.example.com。解决办法是签发时在 SAN 中同时写入 *.example.com 与 example.com,二级子域则单独加 SAN 或使用多域名证书。
配置完成后 Nginx 启动报 key values mismatch 是什么原因?
证书与私钥不配对,常见于重新签发证书后忘记替换私钥、或从多个压缩包里混拿了文件。用 openssl x509 -noout -modulus -in fullchain.crt | openssl md5 与 openssl rsa -noout -modulus -in example.com.key | openssl md5 对比,两行 MD5 必须完全一致;ECDSA 证书改用 openssl ec -pubout 与 openssl x509 -pubkey 对比。不一致只能重新签发,无法通过配置修复。
HSTS 开了之后想回退到 HTTP,为什么浏览器还是强制跳 HTTPS?
HSTS 由浏览器本地缓存生效,服务端改配置无法立即撤销。上线初期应先用 add_header Strict-Transport-Security "max-age=300" always; 短周期灰度,确认无误后再拉长到 31536000 秒;已下发长周期的域名只能等缓存过期,或引导用户清理浏览器 HSTS 列表。
Let’s Encrypt 证书续期成功,为什么线上仍然是旧证书?
续期只更新了磁盘文件,Nginx 进程仍持有旧证书。certbot 需加 --deploy-hook "systemctl reload nginx",acme.sh 需加 --reloadcmd "systemctl reload nginx"。另外若使用 ssl_stapling,reload 后建议再执行一次 openssl s_client -status 确认 OCSP 响应正常。