小程序 SSL 证书怎么选、怎么装:从 CSR 到 HTTPS 全链路实操
一、问题背景与根因:小程序强制 HTTPS 的三条硬约束
很多团队接入小程序时,第一道坎不是业务逻辑,而是后端域名。市面上常把「小程序专用 SSL 证书」当成独立品类来卖,实际上并不存在专门给小程序的证书类型——微信、支付宝、抖音等平台要求的,只是一张由公共受信任 CA 签发、域名匹配、证书链完整、在有效期内的标准 SSL/TLS 证书。理解这一点,后面的选型和部署才不会走弯路。
小程序侧的强制约束主要来自三条:
- 协议白名单:wx.request、wx.uploadFile、wx.downloadFile、wx.connectSocket 只接受 https:// 与 wss://。http:// 请求在真机上被直接拦截,控制台输出
request:fail url not in domain list或errCode: 600001。 - 证书信任链校验:客户端用系统根证书库校验,自签名证书、内部 CA 证书、过期证书、域名不匹配证书一律拒绝,典型报错是
request:fail ssl hand shake error。这个报错不区分具体原因,缺中间证书、TLS 版本过低、SNI 未配置都会长得一模一样,必须用 openssl 逐项排查。 - iOS ATS 要求:苹果 App Transport Security 要求 TLS 1.2 及以上、RSA 密钥 ≥ 2048 位(或 ECC P-256)、签名摘要 SHA-256 及以上,且服务器必须下发完整的中间证书链。否则会出现「Android 正常、iOS 握手失败」——这是最容易被误判成「证书买错了」的场景。
还有两条非证书层面的规则常被忽略:域名必须完成 ICP 备案(境内主体),且不能使用 IP 地址、不能带非标准端口号。也就是说 https://1.2.3.4:8443/api 这种写法在小程序里永远不可用。
结论:选型的核心不是「小程序专用」,而是域名数量、是否需要通配符、是否需要自动化续期这三件事。
二、选型:DV / OV、通配符与 398 天有效期新规
先给结论:小程序后端用 DV(Domain Validation,域名验证型)证书即可,因为微信校验的是「这个域名是否由受信任 CA 确认过控制权」,并不读取证书里的组织信息(O 字段)。OV/EV 证书里的企业名称对小程序的审核没有任何加分,除非甲方合同明确要求。
按覆盖范围分三类:
- 单域名证书:只保护
api.example.com,最便宜。 - 通配符证书:
*.example.com,只匹配一级子域。它覆盖 api.example.com、www.example.com,但不覆盖 test.api.example.com,也不覆盖裸域 example.com(多数 CA 需要额外把裸域加进 SAN)。灰度域、测试域如果层级不同,务必提前列清单。 - 多域名证书(SAN / UCC):一张证书挂多个完全不同的域名,例如 api.example.com + api.example.net + m.example.cn,适合一套后端服务多端复用。
关于有效期,这是旧文章最容易过时的地方,必须更新:自 2020-09-01 起,CA/Browser Forum 规定公共信任证书的单张有效期上限为 398 天;Let’s Encrypt 默认签发 90 天证书。业内已通过决议继续分阶段缩短该上限,因此「买一张用三年」的做法早已失效,到期监控与自动化续期是必选项,不是加分项。
签发时长方面,DV 走 DNS TXT 或 HTTP 文件验证,通常 1-10 分钟出证;OV 需要核验营业执照,1-3 个工作日。上线时间紧就优先 DV。
一个实操建议:证书私钥必须自己生成,把 CSR 交给 CA,而不是让 CA 代生成私钥再打包发给你。私钥一旦离开过你的服务器,HTTPS 的安全性就已经打了折扣。
三、完整实操:从生成 CSR 到合并 fullchain
以 api.example.com 为例,全程在 Linux 服务器上完成。私钥权限必须是 600。以下命令可直接复制执行(单行形式,避免续行符在脚本里出错):
mkdir -p /etc/ssl/example && cd /etc/ssl/example
openssl req -new -newkey rsa:2048 -sha256 -nodes -keyout api.example.com.key -out api.example.com.csr -subj '/C=CN/ST=Beijing/L=Beijing/O=Example Tech/CN=api.example.com'
openssl req -in api.example.com.csr -noout -text | grep -A2 'Subject Alternative Name'
chmod 600 api.example.com.key
如果服务端与客户端都支持 ECDSA,可改用 P-256,握手更快、包更小:
openssl ecparam -genkey -name prime256v1 -out api.example.com.key
openssl req -new -key api.example.com.key -sha256 -out api.example.com.csr -subj '/CN=api.example.com'
提交 CSR 后,CA 会让你做域名验证。DNS 验证最稳(不受 80/443 端口和 CDN 干扰):在解析里加一条 TXT 记录,主机记录形如 _dnsauth.api,值为 CA 提供的随机串,确认生效后再点「验证」:
dig +short TXT _dnsauth.api.example.com
nslookup -type=TXT _dnsauth.api.example.com 8.8.8.8
签发完成后你会拿到两个文件:api.example.com.crt(服务器证书)和 ca_bundle.crt(中间证书)。务必合并成 fullchain,顺序是「服务器证书在前、中间证书在后」,顺序反了同样握手失败:
cat api.example.com.crt ca_bundle.crt > fullchain.crt
grep -c 'BEGIN CERTIFICATE' fullchain.crt
最后确认证书与私钥配对,下面两条命令输出的 MD5 必须完全一致:
openssl x509 -noout -modulus -in api.example.com.crt | openssl md5
openssl rsa -noout -modulus -in api.example.com.key | openssl md5
四、配置示例:Nginx、Spring Boot 与 Node.js
Nginx 配置模板(已包含 HTTP 跳转、TLS 版本收敛、HSTS 与 OCSP 装订):
server {
listen 80;
server_name api.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on;
server_name api.example.com;
ssl_certificate /etc/ssl/example/fullchain.crt;
ssl_certificate_key /etc/ssl/example/api.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;
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/ssl/example/ca_bundle.crt;
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto https;
}
}
几个必须说清的点:ssl_protocols 里不要保留 TLSv1 / TLSv1.1,iOS ATS 与微信均不认可;ssl_certificate 必须指向 fullchain 而不是单张服务器证书,这是「Android 正常、iOS 报错」的头号原因;ssl_stapling 依赖 ssl_trusted_certificate,不配会出现 ssl_stapling ignored, issuer certificate not found;Nginx 1.25.1 起 listen 443 ssl http2; 已废弃,改为 http2 on;,混用会报 the 'listen ... http2' directive is deprecated。
Java 体系不认 PEM,需要转 PKCS#12:
openssl pkcs12 -export -in fullchain.crt -inkey api.example.com.key -name tomcat -out keystore.p12 -passout pass:ChangeMe123
Spring Boot 3.x 的 application.yml:
server:
port: 8443
ssl:
enabled: true
key-store: classpath:keystore.p12
key-store-type: PKCS12
key-store-password: ChangeMe123
key-alias: tomcat
enabled-protocols: TLSv1.2,TLSv1.3
Node.js 原生 https 模块同样要传 fullchain:https.createServer({ key: fs.readFileSync('api.example.com.key'), cert: fs.readFileSync('fullchain.crt'), minVersion: 'TLSv1.2' }, app).listen(443);。注意 Tomcat 的 ciphers 配置只作用于 TLS 1.2 及以下,TLS 1.3 套件由 JVM 参数控制,混配容易把 TLS 1.3 关掉。改完执行 nginx -t && systemctl reload nginx。
五、对比表格:证书类型、CA 与文件格式
表 1:按验证级别与覆盖范围选
| 类型 | 验证方式 | 典型签发时长 | 有效期上限 | 小程序适用性 |
|---|---|---|---|---|
| DV 单域名 | DNS TXT / HTTP 文件 | 1-10 分钟 | 398 天 | 推荐,绝大多数场景 |
| DV 通配符 | DNS TXT | 10 分钟-数小时 | 398 天 | 推荐,子域多且同属一级 |
| DV 多域名 SAN | DNS TXT | 10 分钟 | 398 天 | 推荐,多域名共用一套服务 |
| OV / EV | 企业资质核验 | 1-3 工作日 | 398 天 | 可用但非必需,小程序不读 O 字段 |
| 自签名 | 无 | 即时 | 自定 | 不可用,客户端不信任 |
表 2:免费 ACME 与商业 CA 的取舍
| 维度 | Let’s Encrypt(ACME) | 商业 CA DV |
|---|---|---|
| 有效期 | 90 天 | 最长 398 天 |
| 续期方式 | certbot / acme.sh 全自动 | 手动或 API,多数需人工介入 |
| 信任覆盖 | 主流系统与微信、iOS 均信任 | 同左 |
| OCSP / CRL | 支持 | 支持 |
| SLA 与赔付 | 无 | 有,通常含签发失败赔付 |
| 发票与采购 | 无 | 可开票,便于走采购流程 |
| 适用场景 | 自建服务、CI/CD、域名多 | 企业采购、需要合同与支持 |
表 3:证书文件格式与使用位置
| 格式 | 扩展名 | 典型使用位置 | 注意 |
|---|---|---|---|
| PEM | .crt / .pem / .cer | Nginx、Apache、Node.js、HAProxy | 必须用 fullchain 形式 |
| PKCS#12 | .pfx / .p12 | Tomcat、Spring Boot、IIS | 含私钥,需设置密码 |
| JKS | .jks | 老版 Java 项目 | JDK 9+ 建议迁移到 PKCS12 |
| DER | .der | 部分 IoT 设备、旧版 Android | 二进制格式,不可直接编辑 |
选型口诀:单域先看 DV,子域看层级,多域上 SAN,能自动续期就别手动。如果域名数量超过 5 个且分布在多个主域下,商业多域名证书或全量 ACME 自动化,都比逐张买「小程序专用」套餐更划算。
六、小程序后台域名配置与链完整性自检
证书装好只是第一步,域名必须在微信公众平台登记,否则依旧报 request:fail url not in domain list。路径:微信公众平台 → 开发 → 开发管理 → 开发设置 → 服务器域名,分别填写 request 合法域名、socket 合法域名、uploadFile / downloadFile 合法域名。规则要点:必须是 https:// 开头,不能带端口、不能用 IP、不能是 localhost;域名需已完成 ICP 备案;每月修改次数有限(当前为 5 次),改前先列清单;api.example.com 与 www.example.com 是两个不同域名,不做自动匹配。
- SSL/HTTPS 证书配置 · 证书安装 · 证书申请
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- HTTPS证书申请 · SSL证书安装部署 · 证书续费
配置完用四条命令自检:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts < /dev/null 2>/dev/null | grep -E 'i:|s:'
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 < /dev/null | grep 'Protocol'
openssl verify -CAfile ca_bundle.crt fullchain.crt
openssl x509 -in fullchain.crt -noout -subject -issuer -dates
第 3 条返回 fullchain.crt: OK 说明链完整;返回 error 20 at 0 depth lookup: unable to get local issuer certificate 则说明中间证书没合并进 fullchain。第 4 条用于确认 subject 与 issuer,issuer 必须是对应 CA 的中间证书而不是自签根。
还要注意 CDN / 负载均衡层:如果流量经过 CDN,证书要在 CDN 控制台上传,源站证书只影响回源链路。此时用 openssl 直连源站 IP 排查,会得到和用户侧完全不同的结果。排查顺序永远是「先测用户实际访问的域名,再测源站」。
七、常见错误排查:7 个真实报错与定位命令
1. curl: (60) SSL certificate problem: unable to get local issuer certificate
缺中间证书。把 CA 提供的 ca_bundle.crt 追加到服务器证书后面,重载 Nginx。用 openssl s_client -showcerts 确认返回的证书张数 ≥ 2。
2. nginx: [emerg] SSL_CTX_use_PrivateKey_file() failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)
证书与私钥不配对,通常是续期后只换了 crt 没换 key,或多域名证书拿错文件。用 modulus 对比命令确认 MD5 一致。
3. 微信开发者工具 request:fail ssl hand shake error
不区分原因,逐项排查:TLS 版本是否 ≥ 1.2(openssl s_client -tls1_2 能否握手);证书链是否完整;域名是否与 CN/SAN 完全一致;服务器是否启用 SNI 且返回了正确站点证书。
4. 浏览器 ERR_CERT_COMMON_NAME_INVALID
域名不在证书 SAN 列表里。典型场景是买了 *.example.com 却访问 test.api.example.com——通配符只匹配一级。用 openssl x509 -in fullchain.crt -noout -text | grep -A1 'Subject Alternative Name' 核对。
5. SSL_do_handshake() failed (SSL: error:14094416:SSL routines:ssl3_read_bytes:sslv3 alert certificate unknown)
客户端不信任该证书,多为自签名、证书过期或根证书不在设备信任库。iOS 设备时间不同步还会触发 certificate is not yet valid,用 date -u 与 openssl x509 -noout -dates 对比。
6. 真机正常、开发者工具报错
开发者工具默认勾选「不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」,勾选状态下会掩盖问题。上线前务必取消勾选,真机与工具各测一遍。
7. ERR_HTTP2_PROTOCOL_ERROR
多为 Nginx 版本与 listen ... http2 写法不匹配,或 CDN 回源协议与源站不一致。统一改成 http2 on;,并把 CDN 回源协议设为 HTTPS。
八、效果验证:四层确认与到期监控脚本
第一层:本地连通性
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result}n' https://api.example.com/api/health
期望输出 200 0,其中 0 表示证书校验通过;出现 20 或 60 表示链不完整。
第二层:协议与套件
nmap --script ssl-enum-ciphers -p 443 api.example.com
openssl s_client -connect api.example.com:443 -tls1_3 < /dev/null | grep -E 'Protocol|Cipher'
第三层:第三方评级用 SSL Labs 跑一次(https://www.ssllabs.com/ssltest/analyze.html?d=api.example.com),目标是 A 或 A+。拿 A+ 通常需要:TLS 1.2/1.3 only、开启 HSTS、无 RC4/3DES、OCSP 装订成功。评级页会直接提示 Chain issues: Incomplete,这是最快的链完整性检查手段。
第四层:真机验证关闭开发者工具的域名校验开关,在 iOS 与 Android 各跑一次 wx.request,并在公众平台「开发管理」确认域名状态为已生效。iOS 端要确保小程序侧全部走 https,避免 301 跳转带来额外握手开销。
最后补一个到期监控脚本,防「某天早上突然全站红」:
#!/bin/bash
DOMAIN=api.example.com
END=$(echo | openssl s_client -servername $DOMAIN -connect $DOMAIN:443 2>/dev/null | openssl x509 -noout -enddate | cut -d= -f2)
LEFT=$(( ( $(date -d "$END" +%s) - $(date +%s) ) / 86400 ))
echo "$DOMAIN 剩余 $LEFT 天"
[ $LEFT -lt 30 ] && echo 'WARN: 证书即将过期'
挂到 cron 或监控系统里每天跑一次,比任何人工提醒都可靠。
常见问题
不需要。微信、支付宝等平台只校验证书是否由公共受信任 CA 签发、域名是否匹配、证书链是否完整、是否在有效期内,并不存在专用证书类型。普通 DV 证书(单域名、通配符或多域名 SAN)满足上述条件即可正常使用,价格通常比打包「专用套餐」更低。
只能覆盖同一级子域。*.example.com 匹配 api.example.com、m.example.com,但不匹配 test.api.example.com,也不匹配裸域 example.com。如果接口分散在多级子域或不同主域,应改用多域名 SAN 证书,或按主域分别申请。
自 2020 年 9 月 1 日起,公共信任证书单张有效期上限为 398 天,Let’s Encrypt 为 90 天,业内已通过决议继续缩短。CA 只能签发符合上限的证书,所谓「三年期」实际是分期签发,仍需按期更换,务必配置到期监控与自动续期。
多半是证书链不完整或 TLS 版本过低。iOS 受 ATS 约束,要求 TLS 1.2 以上、RSA 密钥 ≥ 2048 位、SHA-256 签名,且服务器必须下发中间证书。把 ca_bundle 合并进 fullchain 并关闭 TLS 1.0/1.1,通常即可解决。
这是域名未登记,不是证书问题。到微信公众平台「开发管理 → 开发设置 → 服务器域名」,把 https://api.example.com 加入 request 合法域名。注意不能带端口、不能用 IP、域名需已备案,且每月修改次数有限,改前先核对 www 与非 www 的区别。
可以。Let’s Encrypt 的根证书已被主流操作系统和微信客户端信任,用于商用小程序没有兼容性问题。区别在于有效期只有 90 天、无 SLA 与发票。企业若需要采购合同、发票或赔付条款,选商业 CA 的 DV 证书更合适。