跳到主要内容
安装配置教程

小程序 https 要求有哪些?TLS 1.2、证书链、备案与服务器域名白名单的 10 项验收清单

小程序 https 要求 — 小程序 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 合法域名。

  1. 握手三指标:一条命令看协议、校验结果、剩余有效期。必须带 -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) 就是中间证书没配全。

  2. 应用层可达:证书对 ≠ 端口通。
    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 被安全组/防火墙挡住,与证书无关
    
  3. 低版本必须被拒绝。这一步很多团队漏掉,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,务必显式覆盖。

  4. 第三方复核,让工具告诉你缺哪张中间证书。
    # 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 直接指出缺失的中间证书 结果公开、有缓存需刷新
  5. 端上回归:开发者工具里最容易”假通过”。在”详情 → 本地设置”中取消勾选不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书,然后依次调用 wx.request、wx.uploadFile、wx.connectSocket 各一次,期望状态码 200 / 200 / 101(101 为 WebSocket 升级成功),并在真机 vConsole 里确认没有 request:fail。据微信开放文档《网络》章节,服务端域名必须为 HTTPS 且支持 TLS 1.2 及以上。
  6. 持续监控:把续期做成自动化。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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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