跳到主要内容

小程序 request 合法域名校验失败排查:HTTPS 证书链、TLS 1.2 与后台域名配置全流程

一、问题背景:报错长什么样,根因分几类

在小程序里调用 wx.request 时,最常见的两类失败是:

  • request:fail url not in domain list——请求地址不在小程序后台配置的合法域名列表中。
  • request:fail ssl hand shake error——TLS 握手失败,通常由证书链不完整、TLS 版本低于 1.2 或加密套件不兼容导致。

微信对 request、uploadFile、downloadFile、connectSocket 四类接口的域名有硬性约束:必须使用 HTTPS(WebSocket 用 WSS)、证书由受信任 CA 签发且证书链完整、TLS 版本不低于 1.2、只允许 443 端口、域名需完成 ICP 备案(境内主体)、不支持 IP 地址与 localhost。只要有一条不满足,真机上就直接 fail;而开发者工具勾选了「不校验合法域名」时却能跑通,这是最容易误判的地方。

根因可以归为四类:① 后台没配域名,或配置的域名与实际请求域名(含子域名)不一致;② 证书不被信任(自签、过期、缺中间证书、域名不匹配);③ 服务端协议栈不达标(只开 TLS 1.0/1.1,或仅支持已被淘汰的 RSA 套件);④ 域名合规问题(未备案、被云厂商或运营商拦截跳转)。排查顺序建议按「域名配置 → 证书链 → 协议版本 → 备案」逐层收敛,不要一上来就重装证书。

二、第一步:用命令定位故障点

先在服务器或本地终端跑下面四条命令,基本能锁定 90% 的原因:

# 1. 域名解析是否正确(微信侧走公网 DNS)
dig +short api.example.com A

# 2. 443 端口是否可达(安全组/防火墙最常见)
nc -zv api.example.com 443

# 3. 抓取服务端实际下发的证书
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates

# 4. 验证证书链是否完整(关键)
openssl s_client -connect api.example.com:443 -servername api.example.com -verify 5 -verify_return_error </dev/null

第 4 条命令的期望输出是 Verify return code: 0 (ok)。若出现 Verify return code: 21 (unable to get local issuer certificate),说明服务端只下发了站点证书、没带中间证书——这正是 ssl hand shake error 的头号原因。注意 -servername 不能省:同一 IP 上有多张证书时,缺少 SNI 会拿到默认证书,从而误判为域名不匹配。

再看协议版本与加密套件:

openssl s_client -connect api.example.com:443 -tls1_2 </dev/null | grep -E "Protocol|Cipher"
curl -vI https://api.example.com/health --tlsv1.2 --tls-max 1.2

如果 -tls1_2 直接握手失败而默认握手成功,说明服务端把最低版本设成了 TLS 1.3,部分低版本 Android 微信客户端仍以 TLS 1.2 建连,会表现为偶发失败。此时把 ssl_protocols 补上 TLSv1.2 即可。

三、第二步:申请证书并正确安装完整链

小程序只校验「是否被系统信任」,DV 证书完全够用,不必买 OV/EV。免费方案用 Let’s Encrypt,有效期 90 天,必须配置自动续期;商业证书按 CA/B 规则单张最长 398 天,同样需要续期流程。

# 安装 acme.sh 并指定 Let's Encrypt
curl https://get.acme.sh | sh -s email=ops@example.com
~/.acme.sh/acme.sh --set-default-ca --server letsencrypt

# HTTP-01 方式签发(webroot 目录需可写)
~/.acme.sh/acme.sh --issue -d api.example.com -w /var/www/acme --keylength ec-256

# 安装证书:务必用 --fullchain-file 而不是 --cert-file
~/.acme.sh/acme.sh --install-cert -d api.example.com 
  --key-file       /etc/nginx/ssl/api.key 
  --fullchain-file /etc/nginx/ssl/api.pem 
  --reloadcmd      "systemctl reload nginx"

三个高频坑:① --cert-file 只导出叶子证书,链不完整,微信必然握手失败;② 通配符证书 *.example.com 不覆盖 example.com 本身,需同时写两个 -d;③ 微信只看证书的 SAN 扩展,不看 CN,签发时域名必须准确。

装完先确认 PEM 里到底有几张证书:

grep -c "BEGIN CERTIFICATE" /etc/nginx/ssl/api.pem   # 正常应 ≥ 2

结果为 1 说明缺中间证书,需要手动拼接:cat api.crt intermediate.crt > api.pem,顺序是站点证书在前、中间证书在后,根证书不要放进去。

四、第三步:服务端配置示例(Nginx / Apache)

Nginx 最小可用配置,重点是 fullchain、TLSv1.2 与 http2:

server {
    listen 443 ssl;
    http2 on;
    server_name api.example.com;

    ssl_certificate     /etc/nginx/ssl/api.pem;   # 必须是 fullchain
    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;
    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/chain.pem;

    add_header Strict-Transport-Security "max-age=31536000" always;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
}

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}

Apache 对应两行:SSLCertificateFile /etc/httpd/ssl/api.pem(2.4.8 起该指令可直接放 fullchain)与 SSLCertificateKeyFile /etc/httpd/ssl/api.key;老版本需额外用 SSLCertificateChainFile 指向中间证书。

改完执行 nginx -t && systemctl reload nginx。同时注意不要让接口 302 跳到另一个未在小程序后台配置的域名——微信会跟随重定向,最终域名不在白名单里同样报 url not in domain list。小程序端调用保持最简:

wx.request({
  url: 'https://api.example.com/v1/user',   // 不带端口、不用 IP
  method: 'GET',
  timeout: 8000,
  success: (res) => console.log(res.statusCode),
  fail: (err) => console.error(err.errMsg)  // 打印完整 errMsg 便于定位
})

五、第四步:在小程序后台配置服务器域名

路径:微信公众平台 → 开发 → 开发管理 → 开发设置 → 服务器域名。四个输入框分别对应 request 合法域名、socket 合法域名、uploadFile 合法域名、downloadFile 合法域名,需按实际用途分别填写。

  • 只填域名,不带协议、端口、路径:写 api.example.com,不要写 https://api.example.com/,更不要写 api.example.com:8443。
  • 子域名不继承:配置 api.example.com 不会放行 v2.api.example.com,需逐个添加。
  • 不支持 IP、localhost、内网域名;境内主体要求域名已完成 ICP 备案。
  • 四类列表互相独立,只配了 request,上传文件走 uploadFile 仍然失败。
  • 修改次数有限(每月 5 次),改前先确认最终域名,避免额度用完。

保存后在开发者工具点「编译」并清缓存(工具 → 清除缓存 → 全部清除),真机需重新扫码预览。开发阶段可勾选「详情 → 本地设置 → 不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」,但这只对开发者工具与体验版生效,正式版和真机预览仍走完整校验——这就是「电脑上正常、手机上全挂」的根源。

六、对比表格:证书类型与域名写法

选证书时不必纠结品牌,关键看有效期与链是否完整:

证书类型 典型有效期 校验内容 小程序可用 说明
DV 域名型 90 天(Let’s Encrypt)/ 最长 398 天(商业) 域名所有权 可用 免费即可满足,需自动续期
OV 企业型 最长 398 天 域名 + 企业资质 可用 需人工审核,1-3 个工作日
EV 扩展验证 最长 398 天 严格身份核验 可用 浏览器已不展示绿色标识
自签名证书 自定义 无 不可用 不受信任,必报 hand shake error
过期或缺链证书 — — 不可用 握手阶段即失败

后台填写规则同样容易踩坑:

配置项 正确写法 错误写法 后果
request 合法域名 api.example.com https://api.example.com/ 保存被拒绝或校验不通过
端口 不写(默认 443) api.example.com:8443 url not in domain list
子域名 v2.api.example.com 单独添加 只配 api.example.com 子域名请求被拒
主机形式 域名 https://1.2.3.4 不支持 IP,直接失败
协议 HTTPS / WSS HTTP / WS 明文请求被拒绝

七、常见错误排查:真实报错对照

把真机 vConsole 里的 errMsg 原样对照下表,基本可以一步定位:

报错信息 原因 处理
request:fail url not in domain list 域名未配、带了端口/路径、子域名未单独配、302 跳到未配域名 后台按纯域名补全,去掉重定向
request:fail ssl hand shake error 缺中间证书、TLS < 1.2、套件不兼容、多证书缺 SNI 换 fullchain,补 TLSv1.2,检查 server_name
net::ERR_CERT_COMMON_NAME_INVALID 证书 SAN 不含该域名 重新签发含正确域名的证书
curl: (60) SSL certificate problem: unable to get local issuer certificate 证书链不完整 ssl_certificate 指向 fullchain.pem
curl: (60) SSL certificate problem: certificate has expired 证书过期,续期任务失败 手动 acme.sh --renew 并检查 cron
request:fail -102:net::ERR_CONNECTION_REFUSED 443 未监听或安全组未放行 nc -zv 验证,放行入站 443

两个易被忽略的场景:一是域名未备案,请求会被云厂商或运营商拦截并 302 到提示页,小程序侧表现为拿不到预期 JSON 而非直接报错,用 curl -I 看 Location 即可发现;二是 CDN/WAF 回源时把证书换成了自签或过期证书,源站配置正确但边缘节点仍报握手失败,需要在 CDN 控制台重新上传完整证书链。

八、效果验证与到期监控

用一段脚本做上线前体检,覆盖链、协议、到期时间与 HTTP 状态:

#!/usr/bin/env bash
DOMAIN="api.example.com"
echo "== 证书链与协议 =="
openssl s_client -connect $DOMAIN:443 -servername $DOMAIN -verify 5 -verify_return_error </dev/null 2>&1 | grep -E "Verify return code|Protocol"
echo "== 到期时间 =="
echo | openssl s_client -connect $DOMAIN:443 -servername $DOMAIN 2>/dev/null | openssl x509 -noout -enddate
echo "== 请求验证 =="
curl -s -o /dev/null -w "%{http_code} ssl_verify=%{ssl_verify_result}n" https://$DOMAIN/health

ssl_verify_result 为 0 表示链验证通过,配合 SSL Labs(ssllabs.com/ssltest)拿到 A 级即可。随后在微信开发者工具「详情 → 域名信息」确认 request 域名显示为绿色通过,再用真机预览 + vConsole 观察一次真实请求的 statusCode。

监控侧补一条到期告警,把阈值设在 15 天:

END=$(echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -noout -enddate | cut -d= -f2)
DAYS=$(( ( $(date -d "$END" +%s) - $(date +%s) ) / 86400 ))
[ "$DAYS" -lt 15 ] && echo "证书剩余 ${DAYS} 天,请检查续期"

Let’s Encrypt 的 90 天有效期下,15 天阈值能留出足够处理时间。用 ~/.acme.sh/acme.sh --list 确认续期任务已注册,并定期检查 systemctl reload nginx 是否成功——续期成功但未重载,服务端仍在使用旧证书,是最隐蔽的一类失败。

常见问题

是。微信要求 request、uploadFile、downloadFile、connectSocket 全部使用 HTTPS/WSS,且证书由受信任 CA 签发、证书链完整、TLS 版本不低于 1.2、仅允许 443 端口。开发者工具勾选「不校验合法域名」可临时绕过,但正式版和真机预览仍强制校验。


可以。微信只校验证书是否被系统信任、域名是否匹配、链是否完整,不区分 DV/OV/EV。Let’s Encrypt 的 DV 证书完全可用,但有效期只有 90 天,必须配置自动续期;商业证书单张最长 398 天,同样要续期。


绝大多数是证书链不完整,服务端只下发了站点证书而没带中间证书。用 openssl s_client -verify 5 看到 unable to get local issuer certificate 即可确认。改用 fullchain 文件(Nginx 的 ssl_certificate 指向 fullchain.pem)后重载即可。


小程序不继承父域名,子域名必须单独添加。同理,配置时不能带协议、端口和路径,只能填纯域名。另外 request 与 uploadFile 的域名列表相互独立,上传接口要单独在 uploadFile 合法域名里配置。


境内主体的小程序,服务器域名必须完成 ICP 备案,否则请求会被拦截或直接失败。境外主体小程序不要求备案,但仍必须使用 HTTPS、受信任的完整证书链和 TLS 1.2 以上版本,且域名需在小程序后台配置。