小程序后端 SSL 证书部署全流程:选型、申请、Nginx 配置与真实报错排查
为什么小程序必须用 HTTPS:背景与根因
微信小程序从诞生起就把加密通道写死在客户端里:wx.request 只接受 https:// 开头的 URL,wx.connectSocket 只接受 wss://,wx.uploadFile 与 wx.downloadFile 同样如此。这不是“建议最佳实践”,而是客户端强校验,界面上没有任何“继续访问”的按钮可以让用户绕过。所以一个在 Chrome 里能打开、只是地址栏标红的站点,在小程序里会直接失败。
具体有四道门槛,缺一不可:
- 域名合规:必须是完成 ICP 备案的域名,不能是 IP 地址,不能带自定义端口(只走 443),不能是 localhost 或内网域名。
- 后台白名单:域名必须在小程序后台「开发管理 → 开发设置 → 服务器域名」中配置为 request、socket、uploadFile、downloadFile 的合法域名,且每月修改次数有限(当前为 5 次),改之前务必确认。
- 证书可信且链完整:必须由受信任 CA 签发,证书链完整,SAN(Subject Alternative Name)中包含该域名。自签名证书、私有 CA 证书一律不认。
- 协议版本:要求 TLS 1.2 及以上。iOS 端还受 ATS(App Transport Security)约束,要求 SHA-256 签名、RSA 2048 位或 ECC 256 位以上密钥。
根因在于运行环境:小程序跑在微信客户端内,Android 使用系统信任库加微信自身策略,iOS 使用系统 ATS。它不像桌面浏览器那样内置大量根证书、允许用户手动信任,也不会像部分浏览器那样自动补全中间证书——很多老版本 Android 不会主动下载中间证书,这正是“浏览器正常、小程序握手失败”的最常见原因。统计下来,90% 的小程序 HTTPS 报错不是证书买错了,而是链不完整、域名没进白名单、TLS 版本过低这三件事。
动手前先用两条命令自查现状,重点看 Verify return code 是否为 0:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null
curl -v https://api.example.com/ping
证书类型与选型:DV、OV、EV 与域名覆盖范围
按验证等级分为三类。DV(Domain Validation)只验证域名控制权,通过 DNS TXT 记录或 HTTP 文件即可,几分钟签发,是个人站点和小程序 API 的主流选择。OV(Organization Validation)需要营业执照、企业电话核验,通常 1-3 个工作日。EV(Extended Validation)审核最严,需要 3-7 个工作日。
这里必须修正一个流传很广的过时说法:“EV 证书会让浏览器地址栏显示公司名称”已经不成立。Chrome 77(2019 年)起移除了 EV 的绿色地址栏与公司名展示,Firefox、Edge 也已跟进,现在公司名只能在点击锁形图标后的证书详情里看到。EV 今天的价值是组织身份强核验、更高的赔付保险和部分行业合规要求,而不是“地址栏显示”。同理,“证书默认一年有效期”也已过时:CA/Browser Forum 规定公开信任的 TLS 证书单张有效期上限为 398 天,并计划在 2026 年 3 月 15 日缩短到 200 天、2027 年 3 月 15 日缩短到 100 天,续期自动化必须提前规划。
按覆盖范围分为单域名、多域名(SAN)、通配符。通配符 *.example.com 只覆盖一级子域,不覆盖 example.com 本身,也不覆盖 a.b.example.com,这是最常见的选型踩坑点。
| 类型 | 验证内容 | 签发时长 | 覆盖范围 | 适用场景 |
|---|---|---|---|---|
| DV 单域名 | 域名控制权 | 1-10 分钟 | 1 个精确域名 | 小程序 API、个人站点 |
| DV 多域名 SAN | 域名控制权 | 10 分钟左右 | 多个不同域名 | 多业务域名合并 |
| DV 通配符 | 域名控制权 | 10 分钟-1 小时 | *.example.com 一级子域 | 多子域 API 网关 |
| OV | 域名 + 企业资质 | 1-3 个工作日 | 按购买规格 | 企业门户、需合规审计 |
| EV | 域名 + 企业 + 回访 | 3-7 个工作日 | 按购买规格 | 金融、支付类 |
| 签发机构 | 单张有效期 | 续期方式 |
|---|---|---|
| 商业 CA(DigiCert、Sectigo、CFCA 等) | 最长 398 天 | 手动或 API |
| Let’s Encrypt | 90 天 | acme.sh / certbot 自动 |
| ZeroSSL | 90 天 | acme.sh 自动 |
结论:小程序后端 API 用 DV 单域名或 DV 通配符即可,免费证书同样被微信信任,付费买的是保障、审核和人工服务,不是“能不能用”。
申请实操:生成 CSR、DNS 验证与自动签发
无论走商业 CA 还是 ACME,第一步都是生成私钥与 CSR。私钥务必在服务器上生成,不要外传:
mkdir -p /etc/nginx/ssl && cd /etc/nginx/ssl
openssl req -new -newkey rsa:2048 -nodes
-keyout api.example.com.key
-out api.example.com.csr
-subj /C=CN/ST=Zhejiang/L=Hangzhou/O=Example/CN=api.example.com
-addext subjectAltName=DNS:api.example.com,DNS:www.example.com
chmod 600 api.example.com.key
openssl req -in api.example.com.csr -noout -text | grep -A1 'Subject Alternative Name'
注意 -addext 需要 OpenSSL 1.1.1 及以上;旧版本请写一份 openssl.cnf,在 [v3_req] 段里加 subjectAltName=DNS:api.example.com。现代浏览器与微信客户端只认 SAN,CN 字段已不再作为匹配依据,漏写 SAN 会直接导致域名不匹配。
走商业 CA 时,把 CSR 提交给 CA,按提示添加 DNS TXT 记录完成验证,验证通过后下载证书。下载包通常包含三部分:站点证书、中间证书(CA Bundle)、根证书。部署时要的是“站点证书 + 中间证书”的合并文件。
走 Let’s Encrypt 时推荐 acme.sh,全自动且支持 DNS API:
curl https://get.acme.sh | sh -s email=ops@example.com
acme.sh --set-default-ca --server letsencrypt
acme.sh --issue -d api.example.com -d www.example.com --webroot /var/www/html
acme.sh --install-cert -d api.example.com
--key-file /etc/nginx/ssl/api.key
--fullchain-file /etc/nginx/ssl/api.fullchain.pem
--reloadcmd 'nginx -s reload'
两个细节:acme.sh 新版本默认 CA 已改为 ZeroSSL,想用 Let’s Encrypt 必须显式执行 –set-default-ca –server letsencrypt;–fullchain-file 生成的正是“站点证书 + 中间证书”,可以直接喂给 Nginx,不要再用 –cert-file 单独拿站点证书,否则就是链不完整的经典事故。若域名 DNS 托管在阿里云、DNSPod、Cloudflare,可用 –dns dns_ali 之类免去 webroot 配置。验证 DNS 记录是否生效:
dig +short TXT _acme-challenge.api.example.com
Nginx 配置示例:TLS 1.2/1.3、HSTS 与 OCSP Stapling
下面是一份可直接落地的配置,包含 80 跳转、证书链、协议套件、会话缓存、OCSP 装订和反向代理头:
server {
listen 80;
server_name api.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on; # nginx 1.25.1+;旧版写 listen 443 ssl http2;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/api.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:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
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/nginx/ssl/api.chain.pem;
add_header Strict-Transport-Security max-age=31536000 includeSubDomains;
add_header X-Content-Type-Options nosniff;
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto https;
}
}
几个容易踩的点。第一,ssl_certificate 必须指向 fullchain,不能只指向站点证书;ssl_trusted_certificate 指向不含站点证书的中间链文件,供 OCSP 校验使用,两者不能混用。第二,ssl_protocols 里删掉 TLSv1 和 TLSv1.1,微信与主流客户端早已不支持,留着只会拉低安全评级。第三,http2 on 是 nginx 1.25.1 之后的新语法,老版本写了会报 unknown directive。第四,HSTS 一旦下发 max-age=31536000,浏览器会在一年内强制走 HTTPS,回退很麻烦,建议先用 max-age=300 试运行,确认所有子域都支持 HTTPS 后再加 includeSubDomains。
改完必须校验再重载,避免配置错误导致全站 502:
nginx -t && systemctl reload nginx
openssl x509 -in /etc/nginx/ssl/api.fullchain.pem -noout -subject -issuer -dates
Apache、Tomcat、IIS 的等价配置
同一份 fullchain 与 key 可以复用到其他服务端,关键是别丢中间证书。
Apache(httpd 2.4):
<VirtualHost *:443>
ServerName api.example.com
SSLEngine on
SSLCertificateFile /etc/httpd/ssl/api.fullchain.pem
SSLCertificateKeyFile /etc/httpd/ssl/api.key
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite HIGH:!aNULL:!MD5:!3DES
Header always set Strict-Transport-Security max-age=31536000
</VirtualHost>
Apache 2.4.8 之后 SSLCertificateFile 可以直接放 fullchain,不再需要 SSLCertificateChainFile;如果你在旧教程里看到 SSLCertificateChainFile,说明文档已经过时。
Tomcat 需要 JKS 或 PKCS12 格式,先用 OpenSSL 转换:
openssl pkcs12 -export -in /etc/nginx/ssl/api.fullchain.pem
-inkey /etc/nginx/ssl/api.key -out /etc/tomcat/api.p12 -name tomcat -passout pass:changeit
keytool -importkeystore -srckeystore /etc/tomcat/api.p12 -srcstoretype PKCS12
-destkeystore /etc/tomcat/api.jks -deststoretype JKS -deststorepass changeit
<Connector port=443 protocol=org.apache.coyote.http11.Http11NioProtocol SSLEnabled=true>
<SSLHostConfig>
<Certificate certificateKeystoreFile=/etc/tomcat/api.jks
certificateKeystorePassword=changeit type=RSA />
</SSLHostConfig>
</Connector>
IIS 的做法是:导入 .pfx(含私钥),在“服务器证书”中完成导入;若报链错误,需把中间证书单独导入到“中间证书颁发机构”存储;最后在站点绑定里添加 https、端口 443、选中证书并勾选 SNI。多个站点共用 443 时,SNI 必须勾选,否则会返回第一张证书导致域名不匹配。
所有服务端配置完成后,统一用一条命令验证协议与套件:
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null | grep -E 'Protocol|Cipher|Verify'
常见错误排查:从真实报错到定位命令
1)curl: (60) SSL certificate problem: unable to get local issuer certificate
含义是服务端没下发中间证书。用下面的命令数一数返回了几张证书,正常应大于等于 2:
- Wildcard 通配符 SSL 证书安装部署续费申请
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- SSL域名证书申请 · 小程序证书 · 国外SSL证书
- APP/小程序 HTTPS · SSL网站加密证书 · CA证书配置
- NGINX / APACHE / TOMCAT / IIS 证书配置 · SSL证书安装
- 中小企业云服务器安全代运维(防攻击方案)
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'
修复:cat api.crt intermediate.crt > api.fullchain.pem,然后重新加载。
2)curl: (60) SSL: no alternative certificate subject name matches target host name
证书 SAN 不含该域名。检查:
openssl x509 -in api.fullchain.pem -noout -text | grep -A1 'Subject Alternative Name'
常见于用通配符证书去覆盖二级子域 a.b.example.com,或直接访问了 IP。
3)nginx: [emerg] cannot load certificate … PEM_read_bio_X509_AUX() failed
文件不是 PEM 格式(可能是 DER、.pfx,或下载时混入了 HTML 错误页)。用 file 命令确认,再执行 openssl x509 -in api.crt -out api.pem 转换。另外私钥权限必须 600 且属主为 nginx 运行用户。
4)微信开发者工具报 request:fail ssl hand shake error
这是握手层失败,90% 是三种原因:TLS 版本过低(只剩 TLS 1.0)、中间证书缺失(尤其老 Android)、多证书服务器未配 SNI 导致返回默认证书。分别用 -tls1_2 参数测试、检查证书链数量、确认 server_name 命中。
5)不在以下 request 合法域名列表中,请参考文档
纯配置问题,与证书无关。到小程序后台添加域名,注意不能带端口、不能是 IP、必须已备案,且每月修改次数有限。
6)certificate has expired or is not yet valid
服务器时间漂移或证书确实过期。先执行 date -u 对时,再执行 openssl x509 -noout -dates -in api.fullchain.pem 看 notBefore/notAfter。
7)SSL_ERROR_NO_CYPHER_OVERLAP 或 handshake failure
客户端与服务端没有共同套件,通常是服务端禁用了老协议而客户端过旧,或 ssl_ciphers 配置过窄。用 openssl ciphers -v 逐项核对,不要盲目照搬网上配置。
效果验证与到期监控
部署完成不等于交付完成,至少做四层验证。
第一层,命令行握手与证书信息:
openssl s_client -connect api.example.com:443 -servername api.example.com
-CAfile /etc/ssl/certs/ca-certificates.crt </dev/null 2>/dev/null
| grep -E 'Verify return code|Protocol|Cipher'
curl -sI https://api.example.com/api/health | head -n 3
Verify return code 必须为 0,Protocol 应为 TLSv1.2 或 TLSv1.3。
第二层,第三方评级,用 SSL Labs 的 API 一键拉取:
curl -s 'https://api.ssllabs.com/api/v3/analyze?host=api.example.com&publish=off&all=done' | head -c 2000
目标等级 A 及以上,重点看证书链、协议支持、HSTS 三项是否全绿。
第三层,微信侧验证:开发者工具 → 详情 → 项目配置 → 域名信息,确认 request 合法域名已生效;再打开“不校验合法域名”开关做对比测试,若关掉开关就失败、打开就成功,说明问题在域名白名单而非证书。最后必须真机调试,iOS 与 Android 各测一台,因为两端信任库策略不同。
第四层,到期监控。证书过期是小程序线上事故的头号原因,建议在服务器加一条 cron,提前 30 天告警:
if openssl x509 -checkend 2592000 -noout -in /etc/nginx/ssl/api.fullchain.pem; then
echo OK
else
echo EXPIRING | mail -s 'api.example.com 证书即将过期' ops@example.com
fi
使用 acme.sh 或 certbot 的自动续期时,务必确认 –reloadcmd 生效,并每季度手动执行一次 acme.sh –renew -d api.example.com –force 演练,避免自动续期静默失败一年后才发现。
常见问题
小程序一定要买付费 SSL 证书吗?
不一定。微信客户端信任所有主流公共根证书,Let’s Encrypt、ZeroSSL 签发的免费 DV 证书只要链完整、未过期、域名匹配,同样可以正常使用。付费证书买到的是更长的有效期(最长 398 天,免费证书为 90 天)、组织信息核验、赔付保险和人工支持。如果团队没有自动化续期能力,付费证书反而更省心。
通配符证书能覆盖 api.example.com 吗?能覆盖 example.com 吗?
*.example.com 覆盖 api.example.com、www.example.com 这类一级子域,但不覆盖裸域 example.com,也不覆盖多级子域 a.b.example.com。实际部署时通常买“通配符 + 裸域”组合,或者用一张多域名 SAN 证书把两类名字都写进 SAN 列表。
换了证书,小程序需要重新提交审核发版吗?
不需要。小程序只认域名,不认具体证书。只要域名不变、证书链正确、TLS 版本满足要求,换证书对小程序完全透明。但如果换了域名,就必须修改后台服务器域名配置并重新发版。
为什么浏览器打开正常,小程序却报 ssl hand shake error?
最常见是中间证书缺失:桌面浏览器会自动下载缺失的中间证书并补全链条,而微信在部分 Android 机型上不会。其次是 TLS 版本过低或未配置 SNI。排查顺序是先用 openssl s_client -showcerts 数证书数量,再用 -tls1_2 强制握手,最后确认 server_name 是否命中对应 server 块。
证书到期前多久续期比较合适?
商业证书建议提前 30 天,ACME 自动续期在到期前 30 天触发即可。考虑到 2026 年 3 月起公开信任证书有效期将缩短到 200 天、2027 年缩短到 100 天,手工续期会越来越不可行,应尽早把 acme.sh 或 certbot 的自动续期与到期告警一起落地。
一张证书可以同时给小程序 API 和 H5 页面用吗?
可以,只要它们使用同一个域名。同一张证书部署在同一台服务器的 443 端口上,小程序请求和浏览器访问共用即可。若小程序 API 与 H5 分属不同子域,则需要在证书 SAN 中同时包含这两个域名,或改用通配符证书。