跳到主要内容
ssl证书按装

小程序专用 SSL 证书全流程实战:申请、安装、配置与排错(2024 修订版)

小程序专用 SSL 证书全流程实战:申请、安装、配置与排错(2024 修订版) — 小程序专用 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 则直接阻断,所以症状常常是“图片正常、样式全丢”。三种修复手段,从根治到兜底:

  1. 把源码里的绝对地址改成协议相对写法:<script src='//cdn.example.com/a.js'></script>。
  2. 数据库批量替换(以 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');
  3. 服务端加 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 兜底。

内容审核

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