小程序 request 合法域名校验失败(要求 HTTPS):证书链、443 端口与后台配置的完整修复指南
一、报错现象与根因:小程序为什么强制 HTTPS
在小程序里调用 wx.request 时,控制台最常见的几类报错是:
request:fail url not in domain list:请求域名不在小程序后台的服务器域名白名单里。request:fail ssl hand shake error:TLS 握手失败,九成是证书链不完整、协议版本过低或 SNI 未配置。errCode: -1, errMsg: request:fail:笼统失败,需要打开真机 vConsole 看底层网络错误。net::ERR_CERT_AUTHORITY_INVALID、net::ERR_CERT_DATE_INVALID:自签名证书、缺少中间证书或证书已过期。request:fail -2:net::ERR_FAILED:Android 端典型表现,多数由证书链缺失引起。
根因可以归纳为四条硬性约束。第一,协议必须是 HTTPS(wx.request、wx.uploadFile、wx.downloadFile)或 WSS(wx.connectSocket),HTTP 一律拒绝。第二,域名必须完成 ICP 备案,服务器在境内时未备案域名会被运营商层拦截,表现为 302 跳到提示页。第三,域名必须在小程序后台「开发设置 → 服务器域名」中显式配置,且只支持 443 端口,不支持 IP、localhost、带端口号和带路径的写法。第四,TLS 版本与证书本身要合规:iOS 的 ATS 与微信客户端都要求 TLS 1.2 及以上,仍开放 TLS 1.0/1.1 的老服务器会直接握手失败;证书要求 RSA 密钥 ≥2048 位或 ECC ≥256 位、签名算法 SHA-256 及以上、且必须携带完整中间证书链,自签名证书不被信任。
动手前先用一条命令判断问题出在「证书层」还是「配置层」:
curl -v https://api.example.com/ping
# 关注三行输出:
# SSL certificate verify ok. -> 证书层没问题
# subject: CN=api.example.com -> 证书域名是否匹配
# HTTP/2 200 -> 服务是否正常
如果 curl 报 SSL certificate problem: unable to get local issuer certificate,说明服务器没下发中间证书,先解决链问题;如果 curl 正常但小程序仍报 url not in domain list,则纯粹是后台白名单没配或没生效。
二、第一步:申请证书,免费 DV 完全够用(注意有效期新规)
小程序的合法域名校验只看证书是否被系统信任,不看证书品牌,所以免费 DV 证书即可满足。用 acme.sh 申请 Let’s Encrypt 证书,全自动续期:
# 1. 安装 acme.sh
curl https://get.acme.sh | sh -s email=ops@example.com
source ~/.bashrc
# 2. 指定 CA 为 Let's Encrypt
~/.acme.sh/acme.sh --set-default-ca --server letsencrypt
# 3. 方式 A:webroot 校验(网站已在跑 80 端口)
~/.acme.sh/acme.sh --issue -d api.example.com --webroot /var/www/letsencrypt
# 3. 方式 B:DNS API 校验(无公网 80 端口,推荐阿里云 DNS)
export Ali_Key=your_key Ali_Secret=your_secret
~/.acme.sh/acme.sh --issue --dns dns_ali -d api.example.com
# 4. 安装证书并设置续期后自动 reload
~/.acme.sh/acme.sh --install-cert -d api.example.com
--key-file /etc/nginx/ssl/api.example.com.key
--fullchain-file /etc/nginx/ssl/api.example.com.fullchain.pem
--reloadcmd 'nginx -s reload'
有效期必须说清楚,这是很多人踩坑的地方:Let’s Encrypt 证书有效期固定为 90 天;商业 DV/OV/EV 证书受 CA/Browser Forum 约束,自 2020-09-01 起单张证书最长 398 天,并从 2026-03-15 起缩短至 200 天、2027-03-15 起 100 天、2029-03-15 起 47 天。也就是说,任何「买三年一次装好」的思路都已经失效,自动化续期是硬要求。检查续期任务是否生效:
~/.acme.sh/acme.sh --list
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -noout -dates
另外注意信任链变化:Let’s Encrypt 自 2024 年起默认只发 ISRG Root X1 链,Android 7.1 以下的老机型可能不信任,若用户群里仍有大量老设备,可用 --preferred-chain 指定兼容链,或换用商业 DV 证书。
三、第二步:拼出完整证书链并正确部署(最高频的坑)
request:fail ssl hand shake error 有相当比例是因为只部署了站点证书 cert.pem,没有部署中间证书。浏览器有时能靠 AIA 自动补齐,但微信客户端和 Android 系统不做这个补链动作,握手直接失败。正确的文件是 fullchain.pem(站点证书 + 中间证书,顺序不能颠倒),根证书不需要也不建议放入。
# 检查链里到底有几张证书,正常应 >= 2
grep -c 'BEGIN CERTIFICATE' /etc/nginx/ssl/api.example.com.fullchain.pem
# 查看服务端实际下发的证书链
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null | grep -E 'i:|s:|Verify return code'
# 期望输出:
# s:CN = api.example.com
# i:C = US, O = Let's Encrypt, CN = R11
# Verify return code: 0 (ok)
# 如果只有一张,或 verify code 为 21/20,就是缺中间证书
常见错误码含义:Verify return code: 21 (unable to verify the first certificate) 表示链缺失;20 (unable to get local issuer certificate) 表示中间证书未被信任;10 (certificate has expired) 表示证书过期。修复方法很简单,重新 --install-cert 指向 fullchain,或手工合并:
cat api.example.com.crt intermediate.crt > api.example.com.fullchain.pem
nginx -t && nginx -s reload
还有一个隐蔽问题:服务器时间漂移。执行 date -u 与真实时间对比,偏差超过几分钟就会导致校验失败,用 chronyc tracking 或 timedatectl set-ntp true 校时。
四、第三步:Nginx 配置示例(TLS 1.2/1.3 + 80 跳转 443)
以下配置可直接套用,关键点是 ssl_certificate 指向 fullchain、只启用 TLS 1.2/1.3、80 端口强制 301 到 HTTPS,且跳转目标必须是同一个已备案并在小程序后台配置过的域名。
server {
listen 80;
server_name api.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name api.example.com;
ssl_certificate /etc/nginx/ssl/api.example.com.fullchain.pem;
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_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
resolver 223.5.5.5 valid=300s;
add_header Strict-Transport-Security max-age=31536000;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 30s;
}
}
三个易错点:一是 ssl_certificate 写成了 cert.pem,见上一节;二是业务代码里做了到 http:// 或到另一个未配置域名的 302,小程序会判定最终地址不合法,必须在后端把跳转关掉或用 X-Forwarded-Proto 让框架识别真实协议;三是多域名共用 443 时未开 SNI,老版本 Nginx 需要确认编译参数含 --with-http_ssl_module,且每个 server 块都要有自己的证书。改完执行 nginx -t && nginx -s reload,测试方法:curl -I http://api.example.com 应返回 301 且 Location 为 https。
五、第四步:在小程序后台配置服务器域名
证书就绪后,进入微信公众平台 → 开发 → 开发管理 → 开发设置 → 服务器域名,分四类分别配置:request 合法域名、socket 合法域名(WSS)、uploadFile 合法域名、downloadFile 合法域名。四类互相独立,只配了 request 而上传文件时报 uploadFile:fail url not in domain list,就是漏配了。
填写规则很严格:必须填写带 https:// 前缀的完整域名形式,不带路径、不带 query、不带端口(只支持默认 443),不能填 IP 地址,不能填 localhost,域名需已完成 ICP 备案。子域名需单独配置,配置 api.example.com 不会自动覆盖 cdn.example.com。后台对服务器域名有每月修改次数限制,改动前先确认清单。
配置完成后有两个缓存问题要注意:开发者工具需要重新编译(快捷键 Ctrl+B / Cmd+B),最好关掉工具重开;真机上的小程序需要彻底杀掉进程后重新进入,否则旧域名列表仍然生效。开发阶段可以在开发者工具「详情 → 本地设置」勾选「不校验合法域名、web-view(业务域名)、TLS 版本以及 HTTPS 证书」,但这个开关只对模拟器有效,真机预览、体验版、正式版一律按正式规则校验。想用体验版联调,可在手机上打开体验版后点右上角「…」→ 开发调试,开启调试模式再抓日志。
另外,如果页面里用 web-view 嵌入 H5,还需要在「业务域名」中配置并上传校验文件到站点根目录,这是与服务器域名完全不同的另一套白名单。
六、对比表格:证书方案与典型报错对照
先看证书选型,小程序场景只需要「被信任」这一项能力,DV 足矣:
| 方案 | 有效期 | 微信/Android 信任 | 成本 | 适用场景 |
|---|---|---|---|---|
| 自签名证书 | 自定义 | 不信任,必报 ERR_CERT_AUTHORITY_INVALID | 0 | 仅内网调试 |
| Let’s Encrypt DV | 90 天,自动续期 | 信任(ISRG Root X1) | 0 | 绝大多数小程序后端 |
| 商业 DV | 最长 398 天,2026-03-15 起 200 天 | 信任,兼容老 Android | 数百元/年 | 需要更长有效期或商业支持 |
| 商业 OV/EV | 同上 | 信任 | 数千元/年 | 金融、政企合规要求 |
再看报错对照表,按提示直接定位:
| 报错文本 | 根因 | 修复动作 |
|---|---|---|
| request:fail url not in domain list | 后台未配置或未生效 | 补配 request 域名,重新编译/杀进程重进 |
| request:fail ssl hand shake error | 缺中间证书、TLS 版本低、SNI 缺失 | 换 fullchain.pem,启用 TLS 1.2+ |
| net::ERR_CERT_DATE_INVALID | 证书过期或服务器时间错误 | 续期证书,chronyc 校时 |
| request:fail -2:net::ERR_FAILED | Android 证书链不完整 | 补齐中间证书并重启 Nginx |
| HTTP 302 到 http:// 或异域名 | 后端强制跳转、CDN 回源 http | 关闭跳转或改为同域名 https |
这两张表覆盖了 90% 以上的工单场景。注意表中「302 跳转」一项经常被忽略:小程序会跟随重定向,只要最终落地域名不在白名单或协议不是 HTTPS,报错文案仍然是 url not in domain list,容易误导排查方向。
七、常见错误排查:真实报错与处理动作
1)request:fail url not in domain list。先确认后台填的是 https://api.example.com 而不是 https://api.example.com/api,也不能带 :443。再用开发者工具 Network 面板看实际请求 URL 是否被代码拼成了 IP 或测试域名,很多项目在 config.js 里残留了 http://192.168.x.x:8080。
2)request:fail ssl hand shake error。按第三节命令验证链,若 Verify return code 非 0,先补链。若链正常仍失败,检查是否还开着 TLS 1.0:nmap --script ssl-enum-ciphers -p 443 api.example.com,输出里出现 TLSv1.0 就说明配置没生效或前面还有一层旧负载均衡。
3)net::ERR_CERT_AUTHORITY_INVALID。典型是测试环境用了自签名证书,或 CDN 上回源用了自签证书但边缘节点配置错误。小程序不接受任何自签名证书,必须换受信任 CA 签发的证书。
4)证书过期。报 net::ERR_CERT_DATE_INVALID 时先 date -u 看服务器时间,再看证书到期时间。Let’s Encrypt 90 天有效期一旦自动续期失败(常见原因:80 端口被安全组封禁、webroot 路径 404),就会在某天突然全线失败,务必配置到期告警。
5)备案与端口。未备案域名在境内访问会返回 302 到拦截页,小程序侧看到的仍是域名不合法。同时确认安全组放行 443,且没有把 443 映射到 8443 之类的非标端口。
6)多域名混用。主域名配了证书,静态资源却走 cdn.example.com 且未配置 downloadFile 白名单,会出现图片加载失败但接口正常。排查时把 Network 面板里所有域名列一遍,逐个核对后台。
八、效果验证:从命令行到真机的验收清单
改完之后按顺序验收,全部通过再上线。
# 1. 协议与证书校验结果,期望输出 200 0
curl -sS -o /dev/null -w '%{http_code} %{ssl_verify_result}' https://api.example.com/ping
# 2. 证书链完整性,期望 Verify return code: 0 (ok)
openssl s_client -connect api.example.com:443 -servername api.example.com /dev/null | grep 'Verify return code'
# 3. 到期时间与域名匹配
openssl s_client -connect api.example.com:443 -servername api.example.com /dev/null | openssl x509 -noout -subject -enddate
# 4. 80 端口必须 301 到 https
curl -sI http://api.example.com | head -3
# 5. 加密套件评级,建议 SSL Labs 拿到 A
nmap --script ssl-enum-ciphers -p 443 api.example.com
命令行全绿后做真机验证:开发者工具点击「真机调试」,在手机上打开调试面板看 Network,确认请求 URL 为 https、状态 200、无红色证书警告;再用体验版在 4G 网络下走一遍(部分企业内网会做 SSL 中间人,导致仅内网复现失败)。上线后在小程序里加失败上报:
wx.request({
url: 'https://api.example.com/ping',
success: res => console.log('ok', res.statusCode),
fail: err => wx.reportAnalytics('req_fail', { msg: err.errMsg })
});
最后建立两条监控:证书到期前 30 天告警(acme.sh 的 --notify-hook 或外部拨测),以及接口可用性拨测。证书类故障的特点是「某天早上突然全量失败」,提前告警比事后排查划算得多。
常见问题
不需要付费。小程序只校验证书是否被系统信任,免费 DV(如 Let’s Encrypt)完全满足要求,只要部署时使用包含中间证书的 fullchain 文件即可。付费证书的价值主要在于更长的有效期、老设备兼容性和商业支持。
浏览器支持 AIA 自动补链,缺少中间证书也能成功;微信客户端和 Android 系统不做补链,链不完整就直接握手失败。用 openssl s_client -showcerts 检查服务端是否下发了至少两张证书即可确认。[/sg_faq_question]
「不校验合法域名」开关只对模拟器生效,真机预览、体验版和正式版一律按正式规则校验。真机联调只能先把域名配进后台白名单,或在体验版中开启开发调试模式查看日志。