小程序专用 SSL 证书全流程实战:申请、安装、配置与排错(2024 修订版)
一、小程序为什么必须上 HTTPS:背景与根因
微信小程序的网络请求 API(wx.request、wx.uploadFile、wx.downloadFile、wx.connectSocket)从早期基础库起就强制走 HTTPS/WSS。开发者工具里可以勾选“不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书”,但真机预览、体验版和正式版一律强校验,没有任何“继续访问”的例外通道——这就是“小程序专用 SSL 证书”这个说法的由来。证书本身并不特殊,特殊的是小程序的校验规则比浏览器严格得多。
三条硬性门槛:
- TLS 版本 ≥ 1.2。iOS 端 ATS(App Transport Security)要求 TLS 1.2 且加密套件必须支持前向保密(ECDHE),TLS 1.0/1.1 直接握手失败。
- 证书必须由受信任的公共 CA 签发。自签名证书、内网 CA、私有根证书一律失败,因为小程序不读取系统“用户信任区”。
- 域名必须完成 ICP 备案,且不能是 IP 地址、localhost,也不能带非 443 端口。
最常见的根因不是证书买错了,而是证书链不完整:服务器只下发了叶子证书,没有下发中间证书。浏览器可以靠 AIA(Authority Information Access)自动补链,所以你在电脑上看着一切正常;而小程序的网络层和大量 Android 老机型不会自动补链,直接判定证书不可信。先用一条命令确认现状:
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates
如果输出里出现 Verify return code: 0 (ok),说明链完整;出现 unable to get local issuer certificate 或 unable to verify the first certificate,就是缺中间证书。-servername 参数不能省,它模拟 SNI,多域名共用 IP 时省掉会连到错误的站点证书,从而误判为“证书不匹配”。
二、证书选型与有效期新规:DV / OV / EV 对比
选型只需要回答两个问题:验证等级要哪一档、要覆盖几个域名。
| 类型 | 验证内容 | 签发时长 | 典型价格 | 小程序适用性 |
|---|---|---|---|---|
| DV 域名型 | 仅验证域名控制权(DNS TXT / 文件) | 10 分钟内 | 免费 ~ 数百元/年 | 推荐,满足全部技术校验 |
| OV 企业型 | 域名 + 营业执照 + 电话回访 | 1–3 个工作日 | 千元级/年 | 金融、支付类合规要求时使用 |
| EV 增强型 | 域名 + 企业 + DUNS/第三方企业库核验 | 3–5 个工作日 | 数千元/年 | 小程序无额外展示收益 |
| 通配符证书 | *.example.com,仅一级子域 | 同 DV/OV | 随类型浮动 | 子域多且固定时划算 |
| SAN 多域名 | 一张证书绑定多个域名 | 同 DV/OV | 按域名额度计费 | api/upload/ws 多域名首选 |
关于有效期,必须纠正几个流传很广的过时说法:
- 按 CA/Browser Forum 基线要求,公有 TLS 证书单张最长有效期 398 天(2020 年 9 月 1 日起生效)。所谓“买一年”实际是签一张 398 天证书,或者多年订阅分多次签发。
- Let’s Encrypt 免费证书有效期 90 天,官方还提供更短的 6 天档(可选),必须做成自动续期,手工续期迟早出事。
- 行业仍在继续缩短:2026 年 3 月起降至 200 天、2027 年降至 100 天,把续期自动化是唯一正确姿势。
小程序场景下 DV 证书完全够用——小程序不展示 EV 绿色地址栏,Chrome/Safari 也早已取消 EV 的视觉标识。OV/EV 的价值在于企业身份背书和金融、支付类合规要求。域名覆盖上要小心:通配符 *.example.com 既不包括 example.com 本身,也不包括 a.b.example.com,多子域场景直接买 SAN 多域名证书更省事。
三、生成 CSR 与申请证书的完整实操
私钥必须在你自己的服务器上生成,绝不能让服务商代生成后再发给你。
# 1. 生成 2048 位 RSA 私钥(也可用 ECC P-256,更小更快)
openssl genrsa -out api.example.com.key 2048
chmod 600 api.example.com.key
# 2. 生成 CSR,同时写入 SAN —— 现代 CA 忽略 CN,只看 SAN
openssl req -new -key api.example.com.key -out api.example.com.csr
-subj '/C=CN/ST=Guangdong/L=Shenzhen/O=Example Technology Co.,Ltd/CN=api.example.com'
-addext 'subjectAltName=DNS:api.example.com,DNS:upload.example.com'
提交前自检,确认 SAN 已写入且签名有效:
openssl req -in api.example.com.csr -noout -verify
openssl req -in api.example.com.csr -noout -text | grep -A1 'Subject Alternative Name'
不想花钱就用 Let’s Encrypt,用 acme.sh 走 DNS-01 验证,不需要开放 80 端口,特别适合后端在内网或 80 端口被占用的场景:
curl https://get.acme.sh | sh -s email=ops@example.com
~/.acme.sh/acme.sh --issue -d api.example.com -d upload.example.com --dns dns_ali --keylength ec-256
~/.acme.sh/acme.sh --install-cert -d api.example.com
--key-file /etc/nginx/ssl/api.key
--fullchain-file /etc/nginx/ssl/fullchain.pem
--reloadcmd 'nginx -s reload'
从 CA 拿回的通常只有叶子证书,中间证书要自己拼,顺序是“叶子 → 中间”,根证书不要放(放了反而增大握手包并可能引起部分客户端告警):
cat api.example.com.crt intermediate.crt > fullchain.pem
openssl crl2pkcs7 -nocrl -certfile fullchain.pem | openssl pkcs7 -print_certs -noout
四、Nginx 与 Apache 配置示例
Nginx 侧关键是三个点:用 fullchain 而不是单证书、显式限定 TLS 1.2/1.3、开启 OCSP Stapling。TLS 1.3 需要 nginx ≥ 1.13.0 且 OpenSSL ≥ 1.1.1。
server {
listen 443 ssl http2;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 必须含中间证书
ssl_certificate_key /etc/nginx/ssl/api.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_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/chain.pem;
add_header Strict-Transport-Security 'max-age=31536000' always;
location / { proxy_pass http://127.0.0.1:8080; }
}
server {
listen 80;
server_name api.example.com;
return 301 https://$host$request_uri;
}
Apache 等价配置:
<VirtualHost *:443>
SSLEngine on
SSLCertificateFile /etc/httpd/ssl/fullchain.pem
SSLCertificateKeyFile /etc/httpd/ssl/api.key
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
SSLHonorCipherOrder off
Header always set Strict-Transport-Security 'max-age=31536000'
</VirtualHost>
改完必须语法检查再重载,不要直接 restart:nginx -t && nginx -s reload。HSTS 头建议最后再加,一旦下发 max-age=31536000,浏览器在一年内会强制走 HTTPS,回退 HTTP 会直接报错。
五、小程序后台域名配置与校验文件
登录微信公众平台 → 开发 → 开发管理 → 开发设置 → 服务器域名,需要配置五类:request 合法域名、socket 合法域名、uploadFile 合法域名、downloadFile 合法域名、udp 通信域名(如用到)。注意每月修改次数有限(当前为 5 次/月,以官方文档为准),改之前先想清楚。
填写规则很严格:必须是 https:// 开头、必须已备案、不能是 IP、不能带端口、不能是 localhost、不能是短链域名。配置完成后微信会要求上传域名校验文件,把它放到该域名的根目录并通过 HTTPS 可访问:
curl -I https://api.example.com/MP_verify_abcd1234.txt
# 期望:HTTP/2 200,Content-Type: text/plain
curl -s https://api.example.com/MP_verify_abcd1234.txt | md5sum
最常见的坑是 80 端口做了 301 跳转到 www 或跳到别的域名,导致微信校验器拿不到文件内容,校验直接失败。校验文件所在域名必须直出 200,不能有跳转、不能要求登录、不能被 WAF 拦截 UA。
配置后真机验证,如果报 request:fail url not in domain list,说明域名没配、配错分类(比如把 uploadFile 域名配进了 request)、或者请求带了端口;如果报 request:fail ssl hand shake error,则是 TLS 版本或证书链问题,回到第二节用 openssl 复测。
六、HTTPS 后页面错乱:混合内容的根因与修复
“配置完 HTTPS 后页面样式全乱”几乎都不是证书问题,而是混合内容(Mixed Content):页面本身是 https,但 HTML 里硬编码引用了 http 的 CSS、JS、图片。浏览器控制台会明确报:
Mixed Content: The page at 'https://www.example.com/' was loaded over HTTPS,
but requested an insecure stylesheet 'http://www.example.com/style.css'.
This request has been blocked; the content must be served over HTTPS.
注意 Chrome 对图片、音视频会自动升级为 https 重试,对 script/css/iframe 则直接阻断,所以症状常常是“图片正常、样式全丢”。三种修复手段,从根治到兜底:
- 把源码里的绝对地址改成协议相对写法:
<script src='//cdn.example.com/a.js'></script>。 - 数据库批量替换(以 WordPress 为例,务必先备份):
UPDATE wp_posts SET post_content = REPLACE(post_content,'http://www.example.com','https://www.example.com');以及UPDATE wp_options SET option_value = REPLACE(option_value,'http://www.example.com','https://www.example.com'); - 服务端加 CSP 兜底:
add_header Content-Security-Policy 'upgrade-insecure-requests' always;
需要说明:小程序原生 wx.request 不存在混合内容问题,但小程序里 web-view 嵌入的 H5 会,很多“小程序里页面白屏、样式丢失”就是同一个原因。
七、常见错误与真实报错排查
下面这些报错都能在日志或命令行里原样搜到,按表对照即可定位。
| 真实报错 | 根因 | 处理 |
|---|---|---|
curl: (60) SSL certificate problem: unable to get local issuer certificate |
缺中间证书 | 拼 fullchain.pem,并确认 nginx 指向它 |
SSL: no alternative certificate subject name matches target host name |
SAN 里没有该域名 | 重签 CSR,把域名写进 subjectAltName |
curl: (35) error:14094410:SSL routines:sslv3 alert handshake failure |
协议或套件不匹配(老 Android 只支持 TLS 1.0) | 无法兼容,必须升级客户端或加兼容套件 |
x509: certificate has expired or is not yet valid |
证书过期或服务器时间漂移 | 续期证书,ntpdate 校时 |
nginx: [emerg] SSL_CTX_use_PrivateKey_file() failed (SSL: error:0B080074:X509_check_private_key:key values mismatch) |
证书与私钥不配套 | 用 modulus 比对,见下 |
小程序 request:fail ssl hand shake error |
证书链不完整或仅支持 TLS 1.0/1.1 | 补中间证书,开放 TLS 1.2 |
两条定位命令必须会。第一条看完整链路:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null
第二条验证证书与私钥是否配套,两个 MD5 必须完全一致:
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa -noout -modulus -in api.key | openssl md5
八、效果验证与自动续期
配置完成后按三层验证:命令行、在线评级、真机。
# 1. 握手与协议版本
curl -sI https://api.example.com | head -1
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null | grep 'Protocol|Cipher'
# 2. 到期时间
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -noout -enddate
# 3. 在线评级:SSLLabs 目标 A 及以上
# https://www.ssllabs.com/ssltest/analyze.html?d=api.example.com
续期必须自动化,手工续期是证书事故的头号来源:
# certbot 用户
certbot renew --dry-run
systemctl list-timers | grep certbot
# acme.sh 用户(安装时已自动写入 crontab)
0 2 * * * '/root/.acme.sh'/acme.sh --cron --home '/root/.acme.sh' > /dev/null
再加一个到期监控脚本,剩余不足 15 天就告警:
END=$(echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -noout -enddate | cut -d= -f2)
LEFT=$(( ($(date -d "$END" +%s) - $(date +%s)) / 86400 ))
[ $LEFT -lt 15 ] && echo "证书剩余 $LEFT 天" | mail -s 'SSL 到期告警' ops@example.com
最后用微信开发者工具“真机调试”跑一遍真实接口,看 Network 面板返回 200 且无 SSL 告警,才算真正闭环。Android 建议覆盖一台 7.0 以下老机型,很多链不完整的问题只在老系统上暴露。
常见问题
小程序一定要买所谓的“专用 SSL 证书”吗?
不需要。任何受信任公共 CA 签发的标准 TLS 证书都可以,DV 证书即可满足小程序的全部技术校验。所谓“小程序专用”只是服务商包装的服务名称,本质是“证书 + 安装配置服务”。真正决定能否通过校验的是证书链完整性、TLS 版本和域名备案,而不是证书品牌。
免费的 Let’s Encrypt 证书能用于小程序生产环境吗?
可以,兼容性和商业 DV 证书没有区别。唯一代价是有效期只有 90 天,必须用 acme.sh 或 certbot 做好自动续期与 reload 钩子。如果团队没有运维能力,也可以选用 398 天的商业 DV 证书来降低续期频率,但同样建议保留到期监控。
浏览器访问正常,小程序却报 ssl hand shake error,怎么查?
按顺序排查四件事:一是中间证书是否下发,用 openssl s_client -showcerts 看是否只返回一张证书;二是是否还开着 TLS 1.0/1.1,小程序要求 TLS 1.2 以上;三是服务器是否按 SNI 返回了正确站点证书;四是域名是否备案、是否被 CDN 回源配置覆盖。九成案例是第一条。
一张证书能覆盖小程序的多个接口域名吗?
可以。用 SAN 多域名证书(一张通常含 3–5 个域名额度)或通配符证书。注意通配符 *.example.com 只匹配一级子域,不匹配 example.com 本身,也不匹配 a.b.example.com;如果接口分散在 api、upload、ws 等多个子域,SAN 多域名证书更省事也更省钱。
SSL 证书最长能用多久?398 天是怎么来的?
CA/Browser Forum 基线要求规定,2020 年 9 月 1 日起签发的公有 TLS 证书单张有效期不得超过 398 天,这个数字是 13 个月加上必要的续期缓冲。Let’s Encrypt 则固定 90 天。行业计划在 2026 年 3 月缩短至 200 天、2027 年缩短至 100 天,因此自动化续期不是可选项而是必选项。
换成 HTTPS 后页面样式错乱,是证书配置错了吗?
不是。这是混合内容:页面里仍有 http:// 的 CSS、JS、图片引用,浏览器会阻断 script 和 stylesheet。处理方式是把资源地址改成 //cdn.example.com/a.js 这类协议相对写法,或批量把数据库里的 http:// 替换为 https://,最后用 Content-Security-Policy: upgrade-insecure-requests 兜底。