小程序 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 以上版本,且域名需在小程序后台配置。