微信小程序服务器端 HTTPS 配置实战:TLS 1.2 强制启用、证书申请、配置与过期续费全流程
一、问题背景与根因:小程序为何受 HTTPS 与 TLS 1.2 限制
微信小程序的网络请求都通过 wx.request、wx.uploadFile 走客户端系统网络栈:iOS 侧是 NSURLSession,受 ATS(App Transport Security)约束;Android 侧是系统 TLS 实现。因此微信官方对第三方服务器提出硬性要求:域名已完成 ICP 备案、不允许 IP 或 localhost、URL 不允许带端口、必须 HTTPS、TLS 版本不低于 1.2、证书必须由受信任 CA 签发且证书链完整。
开发者最常遇到的报错是开发者工具里的 request:fail ssl handshake error,真机 iOS 上则是 request:fail 未能完成操作。(NSURLErrorDomain 错误 -1200。)。这两类报错九成以上来自三个根因:一是服务器仍启用 SSLv3/TLS 1.0/TLS 1.1,握手阶段直接被拒;二是只部署了叶证书,没有拼接中间证书,部分 Android 机型能通过,iOS 必然失败;三是域名带端口或未备案。
需要纠正几个常见过时认知:其一,Symantec DV 品牌已在 2017—2018 年被 DigiCert 收购并停止独立签发,现在常见的 DV 证书多为 Let’s Encrypt、ZeroSSL、TrustAsia、RapidSSL 等;其二,「一年期证书」已不存在——按 CA/Browser Forum 规定,2020 年 9 月 1 日起公开信任的 TLS 证书最长有效期被限制为 398 天,并计划在 2026 年 3 月缩短至 200 天、2027 年缩短至 100 天、2029 年缩短至 47 天;其三,Let’s Encrypt 证书有效期固定为 90 天,必须依赖自动化续期,靠人工记日历迟早出事。
二、前置条件核对与证书选型
动手前先逐条核对下表,任何一项不满足,后面的配置全部作废。小程序后台「开发管理 → 开发设置 → 服务器域名」提交 request 合法域名时,平台会做一次真实 TLS 握手探测,探测失败直接拒绝保存。
| 检查项 | 合规要求 | 典型违规写法 |
|---|---|---|
| 域名 | 已完成 ICP 备案,如 api.example.com | xxx.ngrok.io、未备案的境外域名 |
| 端口 | 只能 443,URL 中不得出现端口 | https://api.example.com:8443 |
| 主机名 | 必须是域名 | https://127.0.0.1、https://localhost |
| TLS 版本 | ≥ TLS 1.2,禁用 SSLv2/SSLv3/TLS 1.0/TLS 1.1 | 只开 TLS 1.0 的老 Tomcat |
| 证书 | 受信任 CA 签发、域名匹配、含完整中间证书 | 自签名证书、只部署叶证书 |
证书选型:个人与中小项目选 DV(域名验证型)即可,Let’s Encrypt、ZeroSSL、TrustAsia DV 都能通过小程序校验,不必购买 OV/EV。签发方式上,有服务器 root 权限优先用 ACME 协议自动签发与续期;需要泛域名(*.example.com)时走 DNS-01 验证。必须注意有效期变化:Let’s Encrypt 固定 90 天,公开信任的商业证书最长 398 天,且 2026 年起进一步缩短,人工续费窗口越来越窄,必须上自动化。另外,证书私钥务必用 ECC P-256 或 RSA 2048 以上,SHA-1 签名的老证书在 iOS 上会被直接拒绝。
三、用 acme.sh 签发证书并安装(命令可直接执行)
以下命令在 CentOS 7+、Ubuntu 20.04+ 上验证通过,Nginx 与 Apache 通用。webroot 模式不需要停服务,也不会长期占用 80 端口。
# 1) 安装 acme.sh,会自动写入 crontab 做每日续期检查
curl https://get.acme.sh | sh -s email=ops@example.com
source ~/.bashrc
# 2) 新版 acme.sh 默认 CA 是 ZeroSSL,显式切回 Let's Encrypt
acme.sh --set-default-ca --server letsencrypt
# 3) webroot 方式签发(-w 指向站点根目录,需能被 80 端口访问到)
mkdir -p /var/www/html/.well-known/acme-challenge
acme.sh --issue -d api.example.com -w /var/www/html --keylength ec-256
# 4) 泛域名走 DNS 验证(以阿里云 DNS 为例,需先 export Ali_Key/Ali_Secret)
acme.sh --issue --dns dns_ali -d example.com -d '*.example.com' --keylength ec-256
# 5) 安装证书并注册续期后自动 reload
mkdir -p /etc/nginx/ssl
acme.sh --install-cert -d api.example.com --ecc
--key-file /etc/nginx/ssl/api.example.com.key
--fullchain-file /etc/nginx/ssl/api.example.com.crt
--reloadcmd "systemctl reload nginx"
三个必须注意的点:第一,--fullchain-file 装的是「叶证书 + 中间证书」的拼接文件,绝不能只装 cert.pem,否则 iOS 端会报 -1200;第二,--ecc 表示 ECC 密钥,若签的是 RSA 密钥必须去掉该参数,否则 --install-cert 找不到对应目录而报 Can not find domain key path;第三,--reloadcmd 必须写,acme.sh 续期后不会自动重载 Web 服务,配置里会继续使用旧证书直到手工 reload。
四、Nginx / Apache / IIS 配置示例
Nginx(1.25.1 之前请把 http2 on; 写成 listen 443 ssl http2;):
server {
listen 443 ssl;
http2 on;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/api.example.com.crt; # 必须是 fullchain
ssl_certificate_key /etc/nginx/ssl/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:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
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/api.example.com.crt;
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(httpd 2.4):
<VirtualHost *:443>
SSLEngine on
SSLCertificateFile /etc/httpd/ssl/api.example.com.crt
SSLCertificateKeyFile /etc/httpd/ssl/api.example.com.key
# 若 crt 未含中间证书,再补:SSLCertificateChainFile /etc/httpd/ssl/chain.pem
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
SSLHonorCipherOrder off
</VirtualHost>
IIS 用 IIS Crypto 勾选 TLS 1.2 并取消 SSL 3.0,或直接改注册表后重启:
reg add "HKLMSYSTEMCurrentControlSetControlSecurityProvidersSCHANNELProtocolsTLS 1.2Server" /v Enabled /t REG_DWORD /d 1 /f
reg add "HKLMSYSTEMCurrentControlSetControlSecurityProvidersSCHANNELProtocolsTLS 1.2Server" /v DisabledByDefault /t REG_DWORD /d 0 /f
reg add "HKLMSYSTEMCurrentControlSetControlSecurityProvidersSCHANNELProtocolsSSL 3.0Server" /v Enabled /t REG_DWORD /d 0 /f
IIS 还有一步容易漏:中间证书必须导入「中间证书颁发机构」存储,或用 certutil -MergePFX fullchain.crt api.key api.pfx 合并后再绑定,否则同样出现证书链不完整。
五、三种 Web 服务器与证书方案对比
| 维度 | Nginx | Apache | IIS |
|---|---|---|---|
| 协议指令 | ssl_protocols TLSv1.2 TLSv1.3; |
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1 |
注册表 / IIS Crypto |
| 证书链 | ssl_certificate 指向 fullchain | crt + SSLCertificateChainFile | 导入中间 CA 或合并 PFX |
| HTTP/2 | 原生支持 | 需 mod_http2 | Windows Server 2016+ 支持 |
| 重载命令 | systemctl reload nginx |
systemctl reload httpd |
iisreset /noforce |
| Let’s Encrypt 适配 | 优秀 | 良好 | 需 win-acme 客户端 |
| 证书方案 | 有效期 | 成本 | 适用场景 |
|---|---|---|---|
| Let’s Encrypt(ACME 自动) | 90 天,自动续期 | 免费 | 绝大多数小程序后端 |
| ZeroSSL / TrustAsia DV | 90—398 天 | 免费或低价 | 需要控制台管理的团队 |
| 商业 OV 证书 | 最长 398 天 | 数千元/年 | 金融、政企合规要求 |
| 自签名证书 | 任意 | 免费 | 仅内网测试,小程序不可用 |
结论很明确:只要服务器是 Linux 且有 root 权限,ACME 自动续期是最优解;Windows/IIS 环境用 win-acme 同样能实现 90 天自动轮换。上表中自签名证书一栏务必注意——小程序对自签名证书零容忍,本地调试只能在开发者工具里勾选「不校验合法域名」,真机一律失败。
六、常见错误排查(含真实报错)
1. curl: (35) SSL connect error 或 sslv3 alert handshake failure:客户端用 TLS 1.0/1.1 发起握手而服务端已禁用。用 openssl s_client -connect api.example.com:443 -tls1_1 可复现,小程序端对应报错即 request:fail ssl handshake error。修复方式是服务端开启 TLS 1.2/1.3,并推动老客户端升级 TLS 库。
2. curl: (60) SSL certificate problem: unable to get local issuer certificate:证书链不完整,服务端只发了叶证书。浏览器会自动下载中间证书,所以「看起来正常」,但 iOS 和小程序不会补全。用 openssl s_client -connect api.example.com:443 -showcerts 查看,输出只有一段 BEGIN CERTIFICATE 即可确认,改用 fullchain 文件解决。
3. NET::ERR_CERT_COMMON_NAME_INVALID:证书域名与访问域名不一致,例如证书签给 example.com 却访问 api.example.com(通配符 *.example.com 不覆盖三级域名)。用 openssl x509 -in cert.crt -noout -text | grep DNS 查看 SAN 列表核对。
4. 真机报 request:fail 未能完成操作。(NSURLErrorDomain 错误 -1200。):iOS ATS 拒绝,原因通常是 TLS 版本过低、证书链不全或使用了 SHA-1 签名证书。
5. 后台保存域名提示「域名校验不通过」:多为 URL 带了端口或域名未备案。注意 https://api.example.com:443 这种写法也是错的,必须去掉 :443。
七、效果验证:六条命令确认配置正确
# 1) 看协议版本、加密套件与校验结果
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null 2>/dev/null | grep -E "Protocol|Cipher|Verify return code"
# 2) 确认 TLS 1.0 已被拒绝(应输出 alert handshake failure)
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1 2>&1 | head -5
# 3) 校验证书链完整性
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt /etc/nginx/ssl/api.example.com.crt
# 4) 查看到期时间
openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -noout -dates
# 5) 枚举支持的协议与加密套件
nmap --script ssl-enum-ciphers -p 443 api.example.com
# 6) 检查 80 → 443 跳转
curl -sSI http://api.example.com | head -3
期望结果:Verify return code: 0 (ok)、Protocol: TLSv1.2、证书链输出 2 段以上;第 2 条命令必须失败,若仍能握手说明 TLS 1.0 没关干净(注意 Apache 的 SSLProtocol 与 Tomcat 的 sslEnabledProtocols 要分别改)。最后一步是关闭微信开发者工具「详情 → 本地设置 → 不校验合法域名」,在真机预览下调用一次接口,返回 200 即全部通过。
八、过期续费与自动化运维
acme.sh 安装时会写入一条 crontab,执行 crontab -l | grep acme 应看到 0 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh"。它在证书到期前 30 天自动续期,可用 acme.sh --renew -d api.example.com --ecc --force 手动触发一次演练。
确认续期后钩子生效:acme.sh --info -d api.example.com | grep Le_ReloadCmd,输出为空说明安装时没写 --reloadcmd,需要重新执行 --install-cert。到期监控可挂一条 cron,提前 20 天告警:
END=$(echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -noout -enddate | cut -d= -f2)
echo "api.example.com 到期: $END"
商业证书(最长 398 天)到期前 30 天续签,续签后要重新绑定私钥并补齐中间证书。常见坑:Nginx 配置指向软链接但容器内挂载未更新;reloadcmd 写成 restart 导致业务瞬断;IIS 换证书后忘记重启应用池;反向代理(CDN、SLB)上仍是旧证书,回源正常但用户侧已过期。建议把到期时间纳入监控告警,阈值设为 21 天。
常见问题
不行。微信要求最低 TLS 1.2,只开 1.3 会让部分未升级的 Android 机型握手失败。建议同时启用 TLS 1.2 与 TLS 1.3,并禁用 SSLv3、TLS 1.0、TLS 1.1。
不能。公开信任的 TLS 证书最长有效期自 2020 年 9 月起为 398 天,2026 年 3 月起缩短至 200 天,之后继续缩短。Let’s Encrypt 固定 90 天,只能靠 ACME 自动续期。
可以。小程序只校验 CA 是否受信任、域名是否匹配、证书链是否完整、是否在有效期内,与证书价格无关。只要用 fullchain 文件部署,Let’s Encrypt 证书完全可用。[/sg_faq_question]
不需要。证书更新只影响服务端,小程序后台的服务器域名配置保持不变即可。但要注意不能更换域名,否则必须重新修改「服务器域名」并可能触发重新审核。