小程序 SSL 证书申请、安装与配置全流程(微信/百度/抖音/支付宝)
一、问题背景与根因:小程序为什么“必须”上 HTTPS
微信、百度、抖音(字节)、支付宝四家小程序平台在后台“开发设置 → 服务器域名”中都只接受 https:// 开头的域名,wx.request / swan.request / tt.request / my.request 发起的 http:// 请求会被框架直接拦截。更严格的是,小程序运行时没有浏览器的“用户点击继续访问”兜底逻辑:只要证书链不完整、域名不匹配或 TLS 版本低于 1.2,请求立即失败,没有任何忽略警告的选项。这就是同一张证书在 PC 浏览器里小锁正常、在小程序里却报 request:fail ssl hand shake error 的原因。
按实际排障经验,小程序侧证书问题 90% 落在以下四类根因:
- 证书链不完整:只部署了域名证书(leaf),没有拼上中间证书(intermediate)。桌面浏览器会自动通过 AIA 下载中间证书补全链,但 Android 微信、部分 iOS 版本不会,于是握手直接失败。
- 域名不匹配:证书签发的是 example.com,小程序后台填的却是 www.example.com,或者反过来;通配符
*.example.com不覆盖 example.com 本身,也不覆盖 a.b.example.com 这类二级以上子域。 - TLS 版本或加密套件过低:服务端仍开着 TLSv1.0/TLSv1.1,或只提供 RC4、3DES 套件。微信基础库 2.x 以上要求 TLS 1.2 及以上。
- 证书过期或时间异常:有效期已过,或服务器、设备时间偏差导致 notBefore 尚未生效。
另外必须说清有效期规则:自 2020 年 9 月起,CA/Browser Forum 规定公有证书单张最长有效期 398 天(Chrome、Safari 等均强制执行),所以商家口中的“一年证书”实际是 397~398 天;Let’s Encrypt 免费证书固定 90 天。CA/B Forum SC-081 已通过分阶段缩短计划(2026 年起 200 天、2027 年 100 天、2029 年 47 天),把续期做成自动化是唯一可持续的做法。
二、证书选型与价格对比:DV 够用,别为 OV/EV 多花钱
小程序只校验“请求域名是否在证书 SAN 列表里”和“证书链是否可信”,不校验组织信息。因此 DV(域名验证型)证书完全够用,OV/EV 在小程序场景没有任何额外收益,EV 的绿色地址栏也早已被主流浏览器取消。选型只需回答两个问题:要覆盖几个域名、要不要覆盖不限数量的一级子域。
| 证书类型 | 覆盖范围 | 典型场景 | 参考价格 |
|---|---|---|---|
| 单域名 DV | 1 个确切域名(example.com 与 www.example.com 视为两个) | 只有一个 API 入口 | 0 元(Let’s Encrypt)/ 约 200 元/年 |
| 多域名 SAN | 一张证书 2~100 个域名 | api、m、admin 多个入口 | 约 300~800 元/年 |
| 通配符 DV | *.example.com 全部一级子域 | 子域多、经常新增 | 约 600~1500 元/年 |
| 通配符 + 主域 SAN | *.example.com 加 example.com | 主域与子域都要用 | 略高于通配符 |
原文“一年证书 200 元 / 含安装 300 元 / 服务器环境配置 100 元”属于典型的单域名 DV 报价。如果自己动手,用 acme.sh 申请 Let’s Encrypt 成本是 0 元,且能自动续期:
curl https://get.acme.sh | sh -s email=admin@example.com
~/.acme.sh/acme.sh --issue -d example.com -d www.example.com --webroot /www/wwwroot/example.com
~/.acme.sh/acme.sh --install-cert -d example.com
--key-file /etc/nginx/ssl/example.com.key
--fullchain-file /etc/nginx/ssl/example.com.fullchain.pem
--reloadcmd "nginx -t && systemctl reload nginx"
--install-cert 必须带 --reloadcmd,否则 90 天自动续期后证书文件更新了、Nginx 仍持有旧证书,表现为“续期成功但仍提示证书过期”。商业证书同样建议提前 30 天续期。
三、实操一:生成私钥与 CSR(可直接执行)
向 CA 购买证书时,第一步是在自己的服务器上生成私钥和 CSR(Certificate Signing Request)。私钥永远不离开服务器,只把 CSR 交给 CA。以下命令在 OpenSSL 1.1.1 及以上可直接执行:
mkdir -p /root/ssl/example.com && cd /root/ssl/example.com
openssl genrsa -out example.com.key 2048
chmod 600 example.com.key
openssl req -new -sha256 -key example.com.key -out example.com.csr
-subj "/C=CN/ST=Zhejiang/L=Hangzhou/O=Example Tech Co.,Ltd/CN=example.com"
-addext "subjectAltName=DNS:example.com,DNS:www.example.com,DNS:api.example.com"
几个必须注意的点:
- CN 与 SAN 必须一致。现代浏览器和小程序只看 SAN,不看 CN;只在 CN 里写域名、SAN 为空的 CSR 会被 Let’s Encrypt 和多数商业 CA 直接拒绝。
- -addext 需要 OpenSSL 1.1.1+。CentOS 7 自带 1.0.2,会报
req: Unknown option addext,此时改用配置文件:openssl req -new -key example.com.key -out example.com.csr -config san.cnf,在 san.cnf 的 [v3_req] 段写subjectAltName = @alt_names,再逐条列 DNS.1、DNS.2。 - 2048 位 RSA 足够,不必上 4096(握手更慢、老旧 Android 兼容性差);也可选 ECDSA P-256,但要确认 CDN 与小程序端都支持双证书。
- 验证 CSR 内容:
openssl req -in example.com.csr -noout -text | grep -A1 "Subject Alternative Name",输出域名列表必须与提交给 CA 的完全一致。
不要在 CSR 阶段给私钥加密(-des3 等),否则 Nginx 每次启动都要交互输入密码,systemd 管理下会直接启动失败并报 Enter PEM pass phrase: 后超时退出。
四、实操二:域名验证(文件验证与 DNS 验证)
CA 签发前必须证明你控制该域名,主流方式两种:文件验证(HTTP-01)和 DNS 验证(DNS-01)。原文提到的 .well-known/pki-validation/fileauth.txt 就是文件验证,目录与文件名由 CA 指定,一个字符都不能改。
mkdir -p /www/wwwroot/example.com/.well-known/pki-validation
# 将 CA 提供的 fileauth.txt 原样上传,内容通常是 32~64 位 hash
curl -s http://example.com/.well-known/pki-validation/fileauth.txt
# 必须原样返回 hash,不能是 301/302、403、404,也不能是 HTML 页面
Nginx 中要保证 .well-known 不被伪静态、防盗链或强制 HTTPS 跳转拦掉:
location ^~ /.well-known/ {
root /www/wwwroot/example.com;
default_type text/plain;
try_files $uri =404;
}
DNS 验证时,CA 会给出形如 _dnsauth.example.com 的 TXT 记录(Let’s Encrypt 为 _acme-challenge.example.com),添加后用公共 DNS 验证:
dig +short TXT _dnsauth.example.com @8.8.8.8
dig +short TXT _acme-challenge.example.com @1.1.1.1
| 对比项 | 文件验证(HTTP-01) | DNS 验证(DNS-01) |
|---|---|---|
| 是否支持通配符 | 不支持 | 支持 |
| 端口要求 | 80 端口对公网开放 | 无需开放端口 |
| 生效速度 | 秒级,改完即可验证 | 取决于 TTL,通常 1~10 分钟 |
| 常见失败原因 | 301 跳转、WAF 拦截、内容多空格 | TXT 值被截断、同名记录被覆盖、TTL 过长 |
国内服务器若未完成 ICP 备案,80 端口常被运营商侧拦截,文件验证必然失败,此时只能走 DNS 验证。TXT 记录建议临时把 TTL 设为 60,签发成功后再改回原值。
五、实操三:安装配置示例(Nginx / Apache / 宝塔)
拿到证书后第一件事是拼装 fullchain,顺序为“域名证书 → 中间证书”,根证书不要放(会增大握手包,部分客户端反而报警)。
cat example.com.crt intermediate.crt > example.com.fullchain.pem
openssl x509 -noout -subject -issuer -dates -in example.com.fullchain.pem
Nginx 站点配置(关键片段):
server {
listen 443 ssl http2;
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_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
add_header Strict-Transport-Security "max-age=31536000" always;
}
Apache 对应配置:SSLEngine on、SSLCertificateFile /etc/httpd/ssl/example.com.crt、SSLCertificateKeyFile /etc/httpd/ssl/example.com.key、SSLCertificateChainFile /etc/httpd/ssl/intermediate.crt(2.4.8 之前必须单独指定链文件)。
宝塔面板:进入站点 → SSL → 其他证书,证书栏粘贴 fullchain(含中间证书),私钥栏粘贴 .key,保存后开启“强制 HTTPS”。不要在“PEM 格式”栏重复粘贴,否则会生成两份重复证书导致链校验异常。
最后执行 nginx -t && systemctl reload nginx。若报 nginx: [emerg] cannot load certificate "/etc/nginx/ssl/example.com.fullchain.pem": PEM_read_bio_X509_AUX() failed,基本都是文件里混入了证书申请页的 HTML,或缺少 -----END CERTIFICATE----- 结束行。
六、证书链完整性与 TLS 加固验证
部署完成后必须验证服务端实际下发的证书链,而不是只看本地文件。用 s_client 模拟小程序握手:
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -E "^ *[is]:"
正常输出应能看到 2~3 组 s:/i:,且最后一个 i: 是受信任的中间 CA 的上级。若末尾出现 Verify return code: 21 (unable to verify the first certificate),说明只下发了域名证书、缺中间证书;出现 Verify return code: 20 (unable to get local issuer certificate),说明链断在根或中间层;出现 Verify return code: 10 (certificate has expired),直接检查有效期。
加固要点:ssl_protocols 只保留 TLSv1.2 与 TLSv1.3;禁用 RC4、3DES、CBC 类套件;开启 ssl_session_cache 降低握手开销;如有条件开启 OCSP Stapling(ssl_stapling on; ssl_stapling_verify on; ssl_trusted_certificate 指向中间证书链)。HSTS 的 max-age 首次上线建议从 300 秒起,确认全站 HTTPS 无混合内容后再提升到 31536000,否则回退成本很高。
公网复核建议用 SSL Labs(ssllabs.com/ssltest)跑一次完整评级:TLS 1.2/1.3 全绿、证书链完整、无已知漏洞,通常可得 A 或 A+。小程序端对评级不敏感,但对“链完整 + TLS 版本达标”极其敏感,这一步正是为了提前发现链问题。
七、常见错误排查(含真实报错)
| 报错信息 | 根因 | 处理方式 |
|---|---|---|
curl: (60) SSL certificate problem: unable to get local issuer certificate |
服务端未下发中间证书 | 重新拼装 fullchain 并 reload |
request:fail ssl hand shake error |
链不完整、TLS 版本过低或 SNI 未命中 | 用 s_client 复现,检查 ssl_protocols 与 server_name |
net::ERR_CERT_COMMON_NAME_INVALID |
访问域名不在 SAN 列表 | 补签域名或改用通配符证书 |
nginx: [emerg] cannot load certificate ... PEM_read_bio_X509_AUX() failed |
证书文件含 HTML、缺 END 行或权限不足 | 重下证书、chmod 644、检查路径 |
NET::ERR_CERT_DATE_INVALID |
证书过期或客户端时间错误 | 续期并 reload,检查设备时间 |
403 Forbidden(访问 fileauth.txt) |
伪静态/防盗链/强制 HTTPS 拦截 | 加 location ^~ /.well-known/ 例外 |
排查顺序固定为三步:先在服务器本地 curl -vI https://example.com,排除应用层问题;再用 openssl s_client -servername 看链;最后在小程序真机复现。很多“小程序证书错误”其实是域名没在小程序后台“服务器域名”白名单里,或改了域名没重新编译,与证书本身无关。
另一个高频坑:CDN 或负载均衡上装了新证书,但回源服务器仍是旧证书,且 CDN 开启了“跟随协议回源”,导致部分节点握手失败。此时应逐节点验证,或临时关闭回源 HTTPS 定位问题。
八、效果验证与到期监控
部署完成后按以下清单逐项验证,全部通过再提交小程序审核:
# 1. 查看服务端下发的证书链
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -E "^ *[is]:"
# 2. 查看到期时间
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -enddate
# 3. 检查 HTTP 跳转与响应头
curl -sI https://example.com | grep -Ei "strict-transport|HTTP/"
# 4. 检查是否强制跳转 HTTPS
curl -sI http://example.com | head -n 3
小程序侧验证:在微信开发者工具中关闭“不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书”选项后再发请求;真机预览必须使用已在小程序后台登记并生效的域名,域名修改后通常需要数分钟生效,且要重新编译。
到期监控建议做成定时任务,提前 30 天告警:
END=$(echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -enddate | cut -d= -f2)
DAYS=$(( ( $(date -d "$END" +%s) - $(date +%s) ) / 86400 ))
[ "$DAYS" -lt 30 ] && echo "证书剩余 ${DAYS} 天,请续期" | mail -s "SSL 到期告警" ops@example.com
使用 Let’s Encrypt 的场景,务必确认 acme.sh 的 cron 任务存在(crontab -l | grep acme),并定期用 acme.sh --list 核对续期状态。商业证书 398 天有效期同样建议开启日历提醒,避免因遗漏续期导致小程序全线不可用。
常见问题
小程序必须买付费证书吗?免费证书能用吗?
可以用。小程序只校验证书是否由受信任 CA 签发、域名是否匹配、链是否完整,不区分免费或付费。Let’s Encrypt、ZeroSSL 等免费 DV 证书完全满足要求,唯一代价是 90 天有效期,必须配合 acme.sh 或 certbot 自动续期并 reload 服务。若运维能力有限、不希望承担自动续期失败风险,再考虑 398 天的商业 DV 证书。
通配符证书能覆盖多级子域名吗?
不能。*.example.com 只覆盖 a.example.com 这一级,不覆盖 example.com 本身,也不覆盖 a.b.example.com。需要主域与子域同时可用时,应申请“通配符 + 主域 SAN”的组合证书;需要多级子域时,只能为每一级单独申请通配符,或直接使用多域名 SAN 证书逐条列出。
证书有效期最长到底是多少天?为什么总说 398 天?
CA/Browser Forum 规定公有 TLS 证书单张最长有效期 398 天,Chrome、Safari 等会拒绝超期证书,因此商家宣传的“一年证书”实际是 397~398 天。Let’s Encrypt 免费证书固定 90 天。按 SC-081 计划,上限将在 2026 年降至 200 天、2027 年 100 天、2029 年 47 天,长期方案只能是自动化续期。
文件验证一直失败,提示找不到验证文件怎么办?
按顺序排查:用 curl -s http://example.com/.well-known/pki-validation/fileauth.txt 确认返回的是纯文本 hash 而非 HTML;确认没有 301 跳转到 https(CA 默认走 80 端口 HTTP);确认 Nginx 的伪静态规则和 WAF 没有拦截 /.well-known/;确认文件名大小写、内容前后无空格与换行。国内未备案服务器 80 端口被拦截时,改用 DNS 验证即可。
浏览器访问正常,但小程序仍报 ssl hand shake error,怎么定位?
先用 openssl s_client -connect 域名:443 -servername 域名 -showcerts 看链是否完整、Verify return code 是否为 0;再确认服务端是否禁用了 TLSv1.0/1.1。若两者都正常,问题多半不在证书:检查小程序后台“服务器域名”是否已配置并生效、请求域名是否与证书 SAN 完全一致、是否有 CDN 节点回源使用旧证书,以及开发者工具中“不校验合法域名”选项是否仍处于勾选状态。
证书续期成功,为什么线上仍提示证书过期?
最常见原因是只更新了磁盘文件、没有 reload 服务进程,Nginx/Apache 仍持有旧证书。执行 nginx -t && systemctl reload nginx 即可。其次是多节点部署时只更新了其中一台,或 CDN 控制台未同步上传新证书。建议在续期脚本里写死 --reloadcmd,并在续期后重新执行 s_client 校验实际下发证书的到期时间。