跳到主要内容
ssl证书按装

微信小程序服务器端 HTTPS 配置实战:TLS 1.2 强制启用、证书申请、配置与过期续费全流程

微信小程序服务器端 HTTPS 配置实战:TLS 1.2 强制启用、证书申请、配置与过期续费全流程 — 微信小程序服务器端 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]

多半是证书链不完整或 TLS 版本过低。浏览器会自动补全中间证书并回退协议,iOS 与小程序不会。用 openssl s_client -showcerts 检查是否只返回一段证书。


不需要。证书更新只影响服务端,小程序后台的服务器域名配置保持不变即可。但要注意不能更换域名,否则必须重新修改「服务器域名」并可能触发重新审核。

内容审核

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