小程序 https 要求有哪些?TLS 1.2、证书链、备案与服务器域名白名单的 10 项验收清单
小程序 https 要求的核心是四条:域名必须 https/wss 且 TLS 不低于 1.2、证书必须由公共信任 CA 签发并下发完整中间证书链、域名需完成 ICP 备案、域名必须在微信公众平台服务器域名白名单内且只走 443 端口。 一条命令判定是否达标:openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts,输出 Verify return code: 0 (ok) 且 BEGIN CERTIFICATE 出现 2 次即为合格。 证书用 fullchain.pem 而不是 cert.pem,缺中间证书时 Android 端会抛 Trust anchor for certification path not found,而 iOS 端可能正常,导致问题只在部分机型复现。 Let's Encrypt 证书有效期 90 天,certbot 3.x 或 acme.sh 3.x 自动续期即可满足小程序要求,年成本 0 元;商业 DV 单域名约 100-300 元/年,OV 约 1000-4000 元/年,小程序审核并不因 OV 加分。 开发者工具勾选“不校验合法域名、TLS 版本以及 HTTPS 证书”能跑通,不代表真机能跑,验收必须在关闭该选项后用 Android 与 iOS 真机各测一次。
小程序 https 要求到底是什么?为什么开发者工具能跑、真机却报 request:fail
先给结论:小程序 https 要求不是”配个证书”就完事,而是四道关卡叠加——协议(https/wss)、TLS 版本(≥1.2)、证书链与签名算法、域名资质(ICP 备案 + 微信后台白名单)。据微信《小程序网络》文档,wx.request、wx.uploadFile、wx.downloadFile、wx.connectSocket 使用的域名必须为 https/wss,TLS 版本不低于 1.2,域名需完成 ICP 备案,且不支持 IP 地址、localhost 与带端口的写法(只能是 443)。
为什么开发者工具里一切正常,真机却只回一个 request:fail?因为小程序的网络请求由微信客户端代发,不经过你自己的浏览器地址栏,没有”继续访问不安全站点”的交互入口。证书校验一旦失败就静默中断,业务代码拿到的只有一个笼统的 fail,底层原因(握手失败、证书链缺失、域名未登记)全被吞掉。
具体到端上,还有两重系统级约束:iOS 受 ATS(App Transport Security)约束,要求 TLS 1.2 及以上、SHA-256 签名的证书、至少一个 ECDHE 前向保密套件(见 Apple 官方 ATS 文档与 RFC 5246);Android 7.0 以上改用系统信任库校验,服务端若漏发中间证书,会直接抛 CertPathValidatorException,而不是降级放行。第三重是微信侧的业务白名单:域名没在公众平台”开发 → 开发管理 → 服务器域名”里登记,请求在客户端就被拦下,此时证书配得再对也没用,报错固定为 request:fail url not in domain list。
| 校验层 | 触发端 | 典型报错 | 开发者工具能否绕过 |
|---|---|---|---|
| 微信业务白名单 | 客户端,请求发出前 | request:fail url not in domain list |
能(勾选”不校验合法域名…”) |
| TLS 版本 ≥ 1.2 | 系统 TLS 栈 + 微信 | request:fail,无细节 |
能(同一开关) |
| 证书链完整性 | Android 7.0+ 系统信任库 | JS 无报错,日志见 CertPathValidatorException |
能 |
| ATS(TLS1.2 + SHA-256 + ECDHE) | iOS | NSURLErrorDomain -1200 / request:fail |
能 |
所以排查方向应从服务端入手,而不是改前端。用 OpenSSL 一条命令就能定位(OpenSSL 1.1.1 及以上均支持 -tls1_2 与 -servername,后者用于 SNI,缺省不发送):
# 1) 强制 TLS 1.2 握手:若打印 handshake failure,说明服务端未开启 1.2
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null
# 2) 打印完整证书链:正常应看到 depth=1(中间证书)+ depth=0(站点证书)
# 只有 depth=0 即为"缺中间证书",Android 7.0+ 必挂
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null
| grep -E "^(depth|s:|i:)"
# 3) 检查签名算法与密钥,iOS ATS 要求 SHA-256 及以上(sha256WithRSAEncryption / ecdsa-with-SHA256)
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| openssl x509 -noout -text | grep -E "Signature Algorithm|Public-Key|DNS:"
最典型的误判场景:在开发者工具里勾上”不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书”后一切正常,一关掉或一上真机就失败。这个开关只是把上述四层校验全部短路,它证明的是”代码没问题”,恰恰反证了”小程序 https 要求没满足”。此时先跑上面的三条命令看证书链与 TLS 版本,再回公众平台核对服务器域名是否已登记、是否与备案主体一致——顺序反了,就会在代码里白改一整天。
先自查:小程序 https 要求的 10 条硬性条件逐条对照
先把最容易踩的坑说清楚:微信小程序对 https 的要求不是”能打开就行”,而是逐项卡死的硬性条件。上线前用下面这张表逐条打勾,任何一条不通过都会在真机上报 request:fail ssl handshake error 或 request:fail url not in domain list,而开发者工具往往不报错——这也是”工具里好好的,真机全挂”的根本原因。
| 检查项 | 硬性要求 | 不合格时的真实表现 |
|---|---|---|
| ① 协议 | 只允许 https:// / wss://,页面内图片、字体、接口不得混用 http:// |
混合内容被静默拦截,图片空白、接口 0 返回 |
| ② TLS 版本 | 最低 TLS 1.2,建议 1.2 + 1.3 同时开;TLS 1.0/1.1 必须关闭 | ssl handshake error;iOS 端直接失败(Apple ATS 要求 TLS 1.2+) |
| ③ 签发机构 | 公共信任 CA:Let’s Encrypt、DigiCert、Sectigo、云厂商免费 DV | 自签名/内部 CA:CertPathValidatorException: Trust anchor for certification path not found |
| ④ 域名匹配 | 证书 SAN 必须含实际请求的完整域名;www 与非 www 是两个域名;*.example.com 不覆盖 a.b.example.com |
ERR_CERT_COMMON_NAME_INVALID |
| ⑤ 证书链 | 服务端下发”叶子证书 + 中间证书”(根证书不下发) | 部分 Android 机型必失败,浏览器正常 |
| ⑥ 备案 | 域名已完成 ICP 备案,管局审核通常 7–15 个工作日,最长 20 个工作日 | 域名无法录入白名单 |
| ⑦ 端口 | 仅 443;写成 api.example.com:8443 视为域名不合法 |
域名保存时提示格式错误 |
| ⑧ 地址形态 | 不支持 IP、localhost、.local 内网域名、公网不可解析域名 |
保存即校验失败 |
| ⑨ 有效期 | 证书在有效期内,且服务器与客户端系统时间正确 | 过期或时间偏差大导致握手失败 |
| ⑩ 白名单 | request / socket / uploadFile / downloadFile 四类各上限 20 个;修改次数有限(当前文档 50 次/月,早期 5 次/月,以公众平台页面提示为准) | url not in domain list |
下面这组命令可以直接在本地跑,一次性验证 ②④⑤⑨ 四项。据 OpenSSL 官方文档,-servername 用于发送 SNI,缺了它多域名服务器可能返回错误证书:
# 1) 确认协商版本与链校验结果;期望 Protocol: TLSv1.2 且 Verify return code: 0 (ok)
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 &1
| grep -E "Protocol|Cipher|Verify return code"
# 2) 反向探测 TLS 1.1,应报 handshake failure / no protocols available,说明已关闭
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_1 &1 | tail -3
# 3) 查看 SAN 与有效期,确认覆盖实际请求域名
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null
| openssl x509 -noout -subject -dates -ext subjectAltName
# 4) 列出服务端下发的证书数量:应为 2 条(叶子 + 中间),只有 1 条即证书链不全
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts &1
| grep -cE "^ *[0-9]+ s:"
Nginx 侧对应配置如下,fullchain.pem 是 Let’s Encrypt 产出的叶子+中间证书拼接文件,顺序不能颠倒(据 Let’s Encrypt 文档,顺序反了同样会链校验失败):
server {
listen 443 ssl http2;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/fullchain.pem; # 叶子 + 中间证书,缺中间证书部分 Android 必挂
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3; # 显式不写 TLSv1/1.1,RFC 8996 已将其弃用
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers off; # Mozilla 中间兼容配置推荐值
add_header Strict-Transport-Security "max-age=31536000" always;
}
Spring Boot / Tomcat 不能用 PEM,需先把 fullchain 转成 keystore,否则同样只发叶子证书:openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out keystore.p12 -name tomcat,再在 server.ssl.key-store 指向它。最后提醒一句:小程序 https 要求的第 ⑩ 条最容易被忽视——白名单每月修改次数有限,联调阶段先用”不校验合法域名”开关,正式提审前一次性把四类域名配齐,避免把次数耗在反复增删上。
从域名到真机:满足小程序 https 要求的 8 步实操流程
问:从买域名到真机能跑通,最短路径是什么?答:下面 8 步按顺序做,每一步都给出可验证的判据;不要跳步,否则一旦出现证书链问题或白名单问题,就很难区分是哪一个导致的。
第 1 步 · 域名与备案。域名注册成功后,立即在阿里云或腾讯云的代备案系统中提交 ICP 备案(管局审核通常需要 7–20 个工作日,这是整条流程中唯一无法通过技术手段加速的环节)。备案期间可以用测试域名先把链路调通,但正式环境必须使用已备案域名,否则在微信公众平台保存服务器域名时,系统会直接提示“域名不合法”。
第 2 步 · 解析。A 记录指向 CLB(负载均衡)或 Nginx 的公网 IP,用 dig +short api.example.com 确认解析已经生效,再签发证书(HTTP-01 验证依赖解析先通)。
第 3 步 · 签发证书。据 Let’s Encrypt 官方文档,fullchain.pem(站点证书和中间证书)才是需要部署的文件,只部署 cert.pem 会让部分 Android 设备报“证书链不完整”。
# Debian/Ubuntu:certbot 3.x 建议用 snap 安装,apt 源版本常落后
snap install --classic certbot && ln -s /snap/bin/certbot /usr/bin/certbot
certbot certonly --webroot -w /var/www/acme -d api.example.com
--key-type ecdsa --elliptic-curve secp256r1
# certbot ≥2.0 默认即为 ecdsa / secp256r1,此处显式写出便于审计与复现
# 产物目录:/etc/letsencrypt/live/api.example.com/
# fullchain.pem(部署用)、privkey.pem(私钥)、chain.pem(中间证书)
| 维度 | certbot 3.x + Let’s Encrypt | 云厂商免费 DV 证书 |
|---|---|---|
| 单张有效期 | 90 天,可自动续期 | 90 天~1 年,视厂商策略 |
| 续期方式 | systemd timer 自动续期并 reload | 需手动替换或使用控制台一键部署 |
| 适合场景 | 自建 Nginx,有 shell 权限 | 使用 CLB/SLB 等托管入口 |
第 4 步 · 部署与跳转。80 端口做 301 跳转到 443,并保留 ACME 续期通道;443 只开启 TLSv1.2 和 TLSv1.3;如果后端真实服务监听 8443,则由前置 Nginx 做代理转发,对外始终只暴露 443。
server {
listen 80;
server_name api.example.com;
location /.well-known/acme-challenge/ { root /var/www/acme; } # 续期依赖,勿删
location / { 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/letsencrypt/live/api.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3; # 必须显式声明,勿依赖发行版默认值
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305;
location / { proxy_pass https://127.0.0.1:8443; proxy_set_header Host $host; }
}
第 5 步 · 命令行验收。先在本机验证,再动小程序后台,避免把证书问题和白名单问题混在一起排查:
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| grep -E "Protocol|Verify return"
# 期望:Protocol : TLSv1.2 或 TLSv1.3;Verify return code: 0 (ok)
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null
| openssl x509 -noout -enddate # 剩余有效期应 > 30 天
curl -sSI https://api.example.com/health | head -1 # 期望 HTTP/2 200
第 6 步 · 后台登记。在微信公众平台依次进入“开发 → 开发管理 → 服务器域名”,把 request、uploadFile、downloadFile、socket 四类合法域名分别填写,不能混用;每类上限 20 个;域名必须为 https、不能带端口和路径、不能填 IP;保存后必须重新编译小程序才生效。
第 7 步 · 回归。关闭开发者工具“详情 → 本地设置 → 不校验合法域名”,让请求真实走校验流程,回归全部接口。
第 8 步 · 真机。用 Android 与 iOS 各一台设备运行体验版,在 vConsole 的 Network 面板确认接口状态码为 200、WebSocket 升级为 101;只要有一台设备失败,优先怀疑中间证书缺失或设备系统根证书过旧。
命令示例:6 条命令验证域名是否满足小程序 https 要求
清单上的十项验收标准,与其逐条口头确认,不如直接跑六条命令——跑完就知道这个域名能不能过微信审核。下面命令在 OpenSSL 3.0.13、curl 8.5.0(Ubuntu 24.04)实测通过,把 api.example.com 换成你的域名即可复用。
1. 握手与信任链:一次拿到协议、套件和校验结论
# -servername 必带:缺 SNI 会命中默认站点证书,结果无意义
# -CAfile 指定系统根证书库,模拟客户端做完整路径校验
openssl s_client -connect api.example.com:443
-servername api.example.com -showcerts
-CAfile /etc/ssl/certs/ca-certificates.crt < /dev/null
期望输出三行:Verify return code: 0 (ok)、Protocol: TLSv1.3、Cipher: TLS_AES_256_GCM_SHA384。返回码非 0 说明链断;协议为 TLSv1.2 同样合规(据 RFC 8446 与微信开放文档「服务器域名」配置要求,均为 TLS 1.2 及以上),但出现 TLSv1 或 TLSv1.1 直接不通过。
2. 中间证书数量:安卓报 Trust anchor 的根因
# 统计服务端下发的证书条数:2 = 叶子证书 + 1 张中间证书
echo | openssl s_client -connect api.example.com:443
-servername api.example.com -showcerts 2>/dev/null
| grep -c 'BEGIN CERTIFICATE'
返回 1 说明只发了叶子证书。iOS 会靠 AIA 自动补链而“侥幸通过”,Android 则直接抛 Trust anchor for certification path not found——这类故障只在部分机型暴露。修法是把 fullchain.pem(而非 cert.pem)配进服务端。
3. 到期时间与 SAN
# notAfter 剩余天数 + SAN 中的 DNS 条目必须覆盖实际请求域名
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null
| openssl x509 -noout -dates -subject -ext subjectAltName
notAfter 不足 30 天就应进入续期流程(据 Let’s Encrypt 文档,其证书有效期 90 天、建议剩余 30 天时续签)。据 RFC 6125,现代客户端只匹配 SAN,CN 字段早已不参与校验,SAN 缺失就是证书买错了域名。
4. curl 校验结果码
# %{ssl_verify_result} 为 0 才算通过,非 0 按 OpenSSL verify error 编号排查
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result} %{time_total}n'
--tlsv1.2 https://api.example.com/health
| ssl_verify_result | OpenSSL 常量 | 典型原因 |
|---|---|---|
| 0 | X509_V_OK | 校验通过 |
| 10 | X509_V_ERR_CERT_HAS_EXPIRED | notAfter 已过期 |
| 20 | X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY | 缺中间证书或根不受信 |
| 21 | X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE | 链首不完整,同第 2 条 |
| 62 | X509_V_ERR_HOSTNAME_MISMATCH | SAN 未覆盖该域名 |
编号与常量对照见 openssl-verify(1) 手册页,排查时以常量名搜索比记数字可靠。
5. 低版本必须被拒
# 期望握手失败;仍返回 200 说明 TLS 1.0/1.1 没关干净
curl -sS --tlsv1.1 --tls-max 1.1 https://api.example.com/ 2>&1 | head -3
期望看到 sslv3 alert handshake failure 或 unsupported protocol。若握手成功,重点查负载均衡和网关层——小程序 https 要求里的协议版本项,最常被“前面还有一层 SLB”掩盖。
6. 服务端最小配置
// Node.js 20:minVersion 默认即为 'TLSv1.2',显式写出便于审计
const https = require('https');
const fs = require('fs');
https.createServer({
key: fs.readFileSync('/etc/letsencrypt/live/api.example.com/privkey.pem'),
cert: fs.readFileSync('/etc/letsencrypt/live/api.example.com/fullchain.pem'), // 必须 fullchain
minVersion: 'TLSv1.2',
maxVersion: 'TLSv1.3'
}, app).listen(443);
# Nginx 1.26:以下默认值与显式写法一致,注释标注默认值
ssl_protocols TLSv1.2 TLSv1.3; # 默认 TLSv1.2 TLSv1.3(1.23.4 起),勿加 TLSv1/1.1
ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem; # 含中间证书
ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
ssl_prefer_server_ciphers off; # 默认 off,TLS1.3 套件顺序由客户端决定
ssl_session_cache shared:SSL:10m; # 默认 none;10m 约容纳 4 万个会话
nginx -t && systemctl reload nginx
六条命令全部通过,只能证明“传输层合规”;备案主体与服务器域名白名单属于业务侧校验,需要另走微信公众平台的配置流程——两者缺一,请求仍会被拦截在客户端。
证书与 TLS 终止位置怎么选?小程序场景的参数与价格对比
问:小程序的 HTTPS 证书到底该买还是该白嫖?先看这张表。
据 Let’s Encrypt 官方文档,其证书有效期固定为 90 天,官方明确建议以自动化方式续期而非人工提醒;微信小程序侧只要求“HTTPS + TLS 1.2 及以上 + 受信任 CA 签发”,并不区分 DV/OV/EV,所以 OV 的营业执照核验成本换不来审核加分。
| 证书方案 | 现金成本(年) | 有效期 | 续期方式 | 典型适用 |
|---|---|---|---|---|
| Let’s Encrypt DV(单域名/SAN) | 0 元 | 90 天 | certbot 3.x / acme.sh 3.x 自动 | 有基本运维能力的自建后端 |
| Let’s Encrypt 通配符 | 0 元 | 90 天 | 必须 DNS-01 验证 | 子域多且频繁增减 |
| 云厂商免费 DV | 0 元 | 通常 1 年 | 控制台一键部署到 CLB/CDN | 不想维护 ACME 客户端 |
| 商业 DV 单域名 | 100–300 元 | 1 年 | 手动 | 需要发票、SLA 或固定到期日 |
| 商业 DV 通配符 | 500–2000 元 | 1 年 | 手动 | api/upload/ws 等多子域 |
| OV 单域名 | 1000–4000 元 | 1 年 | 手动,需营业执照核验 | 仅合规硬性要求时 |
问:自动续期具体怎么落地?多子域优先用 SAN,一张证书覆盖 api、upload、ws,比分别申请省事;但任一子域下线都要重新签发,这是 SAN 的隐性成本。
# certbot 3.x(含 nginx 插件):一张 SAN 证书覆盖三个子域,续期成功后自动 reload
sudo certbot certonly --nginx
-d api.example.com -d upload.example.com -d ws.example.com
--cert-name example-san
--deploy-hook "systemctl reload nginx" # 关键:只在续期成功时触发
sudo certbot renew --dry-run # 建议每月跑一次,验证续期链路未断
# acme.sh 3.x:通配符只能走 DNS-01,需先在控制台申请 API Key
acme.sh --issue -d example.com -d '*.example.com' --dns dns_ali
acme.sh --install-cert -d example.com
--key-file /etc/nginx/ssl/example.key
--fullchain-file /etc/nginx/ssl/example.fullchain.pem
--reloadcmd "systemctl reload nginx" # 不写这行,续期后 Nginx 仍用旧证书
没监控的 90 天证书是最大隐患:到期当天所有小程序请求会统一报 request:fail ssl hand shake error,而不是零散失败。用 openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts 可确认是否漏发中间证书,典型报错为 verify error:num=20:unable to get local issuer certificate。
问:TLS 在哪一层终止?
| 终止位置 | 证书续期 | 多实例 | 主要风险 |
|---|---|---|---|
| 自建 Nginx 1.26 | 自己写 deploy-hook | 每台需分发证书 | 忘 reload、无到期告警 |
| 云 CLB / ALB | 控制台托管,自动轮转 | 原生支持 | 后端须限内网,避免明文暴露 |
| CDN | 边缘证书自动 | 支持 | 回源段若不启用 HTTPS,回源链路仍是明文 |
| 微信云托管 | 自带默认域名与证书 | 无需处理 | 绑定自定义域名仍需备案 |
问:RSA 还是 ECDSA?RSA 2048 是默认最稳选择;ECDSA P-256 握手包更小、握手更快,仅 Android 5.0 以下不支持(现网占比可忽略)。Nginx 1.11.0 起支持同一 server 块配置双证书,由客户端按套件偏好自选,无需分流:
server {
listen 443 ssl;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/rsa.fullchain.pem; # RSA 2048,兜底
ssl_certificate_key /etc/nginx/ssl/rsa.key;
ssl_certificate /etc/nginx/ssl/ecdsa.fullchain.pem; # ECDSA P-256,优先协商
ssl_certificate_key /etc/nginx/ssl/ecdsa.key;
ssl_protocols TLSv1.2 TLSv1.3; # 默认值随版本不同,务必显式写死,TLS 1.2 是小程序下限
}
成本账别只算钱:单域名 DV 方案年现金成本 0–300 元,真实成本在备案(7–20 个工作日)与续期监控人力上。选型口诀是——实例数少、想完全可控选自建 Nginx + ACME;实例多、不想碰 shell 选云 CLB 托管;用 CDN 就一定把回源也切成 HTTPS,否则“小程序 HTTPS 合规”只是表面合规。可参考 Mozilla SSL Configuration Generator 生成基线配置,并结合 RFC 8446(TLS 1.3)核对协议版本。
常见报错与排查:小程序 https 要求不满足时的真实报错信息
这三类报错来自完全不同的校验层,混在一起排查最容易走弯路:域名白名单是微信客户端的业务校验(与证书无关)、握手失败是 TLS 协议层、COMMON_NAME_INVALID 与 Trust anchor 异常是证书身份与证书链层。先按下表定位到层,再动手。
| 报错原文(可在真机日志/控制台搜索) | 触发层 | 根因 | 一行修复 |
|---|---|---|---|
| request:fail url not in domain list | 白名单 | 域名未登记、只登记了 example.com 却请求 api.example.com、或 URL 带端口 | 公众平台「开发管理 → 服务器域名」补齐 request 合法域名 |
| request:fail ssl hand shake error | TLS 握手 | 证书过期、证书链不全、仅支持 TLS 1.0/1.1 | 用 openssl s_client 看 Protocol 与 Verify return code |
| net::ERR_CERT_COMMON_NAME_INVALID | 证书身份 | 证书 SAN 不含实际访问域名 | 重签含该域名或改用通配符证书 |
| Trust anchor for certification path not found | 证书链 | 服务端只下发叶子证书 | ssl_certificate 改指 fullchain.pem |
| curl: (60) unable to get local issuer certificate | 证书链 | 同上,中间证书缺失 | 同上 |
| 域名不合法 / 请先完成备案 | 平台校验 | 未备案、填 IP、填端口、非公网可解析 | 备案通过后重新提交 |
Q:request:fail url not in domain list 是不是证书没配好?
不是。这条报错发生在发起请求之前,小程序 https 要求里的白名单与证书是两套独立校验。注意三点:白名单按完整子域名精确匹配,登记 example.com 不会放行 api.example.com;域名不能带端口和路径;修改后需重新编译并在真机重进小程序才生效,开发者工具缓存常造成”改了没用”的错觉。
Q:request:fail ssl hand shake error 怎么快速定位?
在任意有网络的机器上复现,-servername 不能省,否则 SNI 缺失会拿到默认站点证书,误判为域名不匹配:
# 复现握手,只看协议版本与校验结果两行(OpenSSL 1.1.1+ / 3.x 通用)
openssl s_client -connect api.example.com:443
-servername api.example.com -showcerts /dev/null
| grep -E 'Protocol|Verify return code'
# 正常输出示例:
# Protocol : TLSv1.3
# Verify return code: 0 (ok)
# 若显示 Protocol : TLSv1,说明服务端仍开放 TLS 1.0,不满足小程序 https 要求
# 若显示 Verify return code: 21 (unable to verify the first certificate),即缺中间证书
补充一个坑:OpenSSL 3.x 默认 security level 1 会直接拒绝 TLS 1.0/1.1 握手,输出 no protocols available,这本身就说明服务端协议版本过低。
Q:为什么 iOS 正常、只有部分 Android 机型报 Trust anchor?
因为 Android 7.0+ 起不再信任用户安装的中间证书,而 iOS 有 AIA 补链机制,会自己去证书扩展里的 URL 抓中间证书,于是掩盖了服务端配置缺陷。修法在 Nginx 侧:
server {
listen 443 ssl;
server_name api.example.com;
# 关键行:必须用 fullchain.pem(叶子+中间),只写 cert.pem 会缺中间证书
ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
# 小程序 https 要求 TLS 1.2 及以上,Nginx 默认值 ssl_protocols 在 1.23.4+ 已为 TLSv1.2 TLSv1.3
ssl_protocols TLSv1.2 TLSv1.3;
}
# 改完执行 nginx -t && nginx -s reload
据 Let’s Encrypt 文档,fullchain.pem 即 cert.pem 与 chain.pem 的拼接,这正是补链的官方做法。验证链是否补全,看证书条数,正常返回 2:
grep -c 'BEGIN CERTIFICATE' /etc/letsencrypt/live/api.example.com/fullchain.pem
# 输出 2 = 叶子 + 中间;输出 1 = 只下发了叶子证书
# 本地校链,-untrusted 传入中间证书,报错信息与 curl (60) 同源
openssl verify -untrusted chain.pem cert.pem
# 缺失时:error 21 at 0 depth lookup: unable to verify the first certificate
Q:保存域名时提示”域名不合法”要先备案吗?
据微信公众平台文档,服务器域名须为已备案、公网可解析的域名,且不能填 IP、端口、路径。逐项核对:dig +short api.example.com 是否有 A 记录、域名是否在工信部备案系统可查、填的是否为纯域名。备案通过后重新提交即可,与重装证书无关。
证书装完不等于小程序能连上——真正要验的是”链路 + 应用层 + 客户端”三段。下面 6 项动作按顺序跑完,任一项失败就先别发版。所有命令中的 api.example.com 换成你自己的 request 合法域名。
- 握手三指标:一条命令看协议、校验结果、剩余有效期。必须带
-servername,否则不发 SNI,服务器会返回默认站点的证书,这是最常见的误判来源。# 看协议版本与链校验结果 echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | grep -E 'Protocol|Verify return code' # 合格输出示例(缺一不可): # Protocol : TLSv1.2 # Verify return code: 0 (ok) # 看到期时间,notAfter 需距今 > 30 天 openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null | openssl x509 -noout -enddate注意
Verify return code非 0 时常见的21 (unable to verify the first certificate)就是中间证书没配全。 - 应用层可达:证书对 ≠ 端口通。
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result}n' https://api.example.com/health # 合格输出:200 0 # 若出现 curl: (7) Failed to connect ... Connection timed out # 说明 443 被安全组/防火墙挡住,与证书无关 - 低版本必须被拒绝。这一步很多团队漏掉,TLS 1.1 未关会同时踩到合规扫描和小程序兼容性两个坑。
curl -sS --tls-max 1.1 https://api.example.com/health # 期望失败,不得返回 200 echo | openssl s_client -connect api.example.com:443 -tls1_1 2>&1 | head -3 # 合格输出类似:sslv3 alert handshake failure / no protocols available据 IETF RFC 8996(2021 年 3 月),TLS 1.0/1.1 已被正式弃用。nginx 从 1.23.4 起
ssl_protocols默认值才是TLSv1.2 TLSv1.3,更早版本默认仍包含 TLSv1/1.1,务必显式覆盖。 - 第三方复核,让工具告诉你缺哪张中间证书。
# testssl.sh 3.2(2023 年发布),可本地跑、可进 CI ./testssl.sh --quiet --color 0 api.example.com | grep -E 'Chain|Grade|TLS 1' # 或浏览器打开 https://www.ssllabs.com/ssltest/ ,勾选 "Do not show the results on the boards"Chain issues 应为
None,评级 A 及以上。SSL Labs 会直接点名 This server’s certificate chain is incomplete,比手工比对省时间。完整链顺序为 叶子证书 → 中间证书(根证书可省略,客户端自带)。工具 版本/形态 关键判据 优势 局限 testssl.sh 3.2,本地脚本 Chain / Grade / 协议枚举 可进 CI,域名不外泄 不模拟微信客户端 UA Qualys SSL Labs 在线服务 Chain issues: None、Overall Rating 直接指出缺失的中间证书 结果公开、有缓存需刷新 - 端上回归:开发者工具里最容易”假通过”。在”详情 → 本地设置”中取消勾选不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书,然后依次调用
wx.request、wx.uploadFile、wx.connectSocket各一次,期望状态码200 / 200 / 101(101 为 WebSocket 升级成功),并在真机 vConsole 里确认没有request:fail。据微信开放文档《网络》章节,服务端域名必须为 HTTPS 且支持 TLS 1.2 及以上。 - 持续监控:把续期做成自动化。Let’s Encrypt 证书有效期 90 天,官方建议剩余 30 天内续期;同时设 30/14/7 天到期告警兜底。
# certbot certbot renew --deploy-hook 'nginx -s reload' # acme.sh(--reloadcmd 在续期成功后执行) acme.sh --install-cert -d api.example.com --key-file /etc/nginx/ssl/api.key --fullchain-file /etc/nginx/ssl/api.pem --reloadcmd 'nginx -s reload'续期后域名不变,就无需回小程序后台重新登记服务器域名白名单;只有换域名或换主体才需要重新配置。
wss 与业务域名:容易被忽略的两类小程序 https 要求
很多团队把 request 合法域名配好就以为完事了,结果上线后 WebSocket 连不上、图片加载报错、业务域名保存失败。小程序 https 要求在 wss 和业务域名这两块有独立规则,与普通 request 请求并不共用同一套配置。
wx.connectSocket 为什么必须用 wss://?端口还是 443 吗?
是。据微信开放文档,wx.connectSocket 的 url 必须是 wss:// 协议,且端口只能是 443(不写端口即默认 443,写其他端口会被拒绝)。这意味着你的网关不仅要完成 TLS 握手,还要允许 HTTP Upgrade: websocket 头透传,并在负载均衡层保持长连接。云厂商 CLB/ALB 的会话空闲超时默认常见为 60 秒,若业务心跳间隔大于该值,典型表现是「连接建立后几十秒无数据、随后断开」。
# Nginx 反向代理 WebSocket:关键在 Upgrade / Connection 两个头
# 适用:nginx 1.18+(http_proxy 模块内置)
location /ws/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1; # 必须,1.0 不支持 Upgrade
proxy_set_header Upgrade $http_upgrade; # 透传 Upgrade: websocket
proxy_set_header Connection "upgrade"; # 固定为 upgrade,不能沿用 close
proxy_read_timeout 120s; # 大于心跳间隔,默认 60s 易断
proxy_send_timeout 120s;
}
对应地,小程序端心跳建议 30 秒一次:setInterval(() => socket.send('ping'), 30000),小于服务端 120 秒的读超时即可。
业务域名校验文件放错路径会怎样?
web-view 打开的外部页面必须把域名登记为业务域名,微信会要求把 XXXXXXXX.txt 放到该域名 https 根目录下(即 https://example.com/XXXXXXXX.txt)并可直接公网访问。若文件返回 404、被重定向到登录页、或 Content-Type 被改写成 text/html,小程序后台保存时会直接失败。域名本身同样需要完成 ICP 备案。
# 自检:状态码 200、无 301/302、内容与后台给出的一致
curl -sS -o /dev/null -w '%{http_code} %{content_type}n'
https://example.com/XXXXXXXX.txt
# 期望输出:200 text/plain
哪些域名要单独登记?一张表说清
| 能力 | 对应配置项 | 典型报错 | 能否互相顶替 |
|---|---|---|---|
wx.request |
request 合法域名 | url not in domain list | 否 |
wx.connectSocket |
socket 合法域名 | url not in domain list | 否 |
wx.uploadFile |
uploadFile 合法域名 | url not in domain list | 否 |
wx.downloadFile |
downloadFile 合法域名 | url not in domain list | 否 |
| web-view 页面 | 业务域名 | 后台保存失败 | 否 |
图片若走独立 CDN 域名,该 CDN 域名必须单独登记到 downloadFile 列表,否则 <image> 在真机上报 url not in domain list(开发者工具可勾选「不校验合法域名」绕过,这也是很多问题只在真机暴露的原因)。
换证书要重新登记白名单吗?
不需要。白名单校验的是域名,不校验证书品牌或密钥算法。从 RSA 2048 换成 ECDSA P-256、从 DV 换 OV、续期换发,都不影响已有登记;只有域名本身变化才需修改,且受每月修改次数限制(据微信开放文档,每月可修改次数有限,务必一次改对)。另外,微信云开发的默认域名无需备案即可访问,但仅限访问云开发资源;一旦改为自建后端或自有 CDN,就必须使用已备案域名并部署完整证书链(含中间证书),这与 wx.request 的 TLS 1.2 要求一致。
不能。微信要求服务器域名必须为 https/wss,TLS 版本不低于 1.2,且不支持 IP 与端口写法。开发者工具里勾选“不校验合法域名、TLS 版本以及 HTTPS 证书”可以让 http 请求暂时跑通,但真机与体验版会直接失败,不能作为上线依据。
都不支持。小程序走微信客户端的系统信任库,自签名证书与私有 CA 不在信任列表内;服务器域名也只接受已在公网可解析、且完成 ICP 备案的域名,填 IP 或 localhost 会提示域名不合法。
要求不低于 TLS 1.2。TLS 1.0/1.1 在 iOS ATS 与主流 CA 策略下已不被接受,建议服务端只开 TLSv1.2 与 TLSv1.3。可用 curl –tlsv1.1 –tls-max 1.1 验证,期望握手失败。
这是白名单问题,不是证书问题。到微信公众平台 → 开发 → 开发管理 → 服务器域名,按 request/uploadFile/downloadFile/socket 四类补录完整域名(注意 www 与非 www 是两个域名),保存后重新编译小程序。每月修改次数有限,提交前先核对拼写与端口。
可以满足。Let's Encrypt 是公共信任 CA,DV 证书在小程序校验中与付费 DV 等效,区别只在有效期 90 天、需要自动续期,以及没有商业 SLA 与人工支持。付费 DV 约 100-300 元/年、OV 约 1000-4000 元/年,主要价值在有效期更长、责任保障与合规审计,不影响小程序能否请求成功。
服务端只下发了叶子证书,没带中间证书。iOS 会自动补链,Android 部分机型不会,于是只在 Android 复现。把 Nginx 的 ssl_certificate 指向 fullchain.pem,再用 openssl s_client -showcerts 确认 BEGIN CERTIFICATE 出现 2 次即可。
不需要。只要域名不变,续期、换品牌、RSA 换 ECDSA 都不影响白名单,客户端只校验域名与证书链。只有新增或更换域名时才需要改服务器域名,并注意每月修改次数限制。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。