跳到主要内容
ssl证书按装

小程序 SSL 证书怎么选、怎么装:从 CSR 到 HTTPS 全链路实操

小程序 SSL 证书怎么选、怎么装:从 CSR 到 HTTPS 全链路实操 — 小程序 SSL 证书怎么选、怎么装:从 CSR 到 HTTPS 全链路实操

一、问题背景与根因:小程序强制 HTTPS 的三条硬约束

很多团队接入小程序时,第一道坎不是业务逻辑,而是后端域名。市面上常把「小程序专用 SSL 证书」当成独立品类来卖,实际上并不存在专门给小程序的证书类型——微信、支付宝、抖音等平台要求的,只是一张由公共受信任 CA 签发、域名匹配、证书链完整、在有效期内的标准 SSL/TLS 证书。理解这一点,后面的选型和部署才不会走弯路。

小程序侧的强制约束主要来自三条:

  1. 协议白名单:wx.request、wx.uploadFile、wx.downloadFile、wx.connectSocket 只接受 https:// 与 wss://。http:// 请求在真机上被直接拦截,控制台输出 request:fail url not in domain list 或 errCode: 600001。
  2. 证书信任链校验:客户端用系统根证书库校验,自签名证书、内部 CA 证书、过期证书、域名不匹配证书一律拒绝,典型报错是 request:fail ssl hand shake error。这个报错不区分具体原因,缺中间证书、TLS 版本过低、SNI 未配置都会长得一模一样,必须用 openssl 逐项排查。
  3. 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 是两个不同域名,不做自动匹配。

配置完用四条命令自检:

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 证书更合适。

内容审核

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