跳到主要内容

小程序 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]

常见原因有三个:请求 URL 带了端口或路径;代码里仍指向测试 IP 或其他子域名;客户端缓存了旧的域名列表。重新编译开发者工具,真机上彻底杀掉小程序进程再进入即可刷新。[/sg_faq_question]

不支持。服务器域名只允许默认端口,HTTPS 固定 443,WSS 同样固定 443,填写时也不能带端口号。如果后端服务跑在 8443,需要用 Nginx 做 443 反向代理。[/sg_faq_question]

Let’s Encrypt 固定 90 天;商业证书受 CA/Browser Forum 限制,目前单张最长 398 天,2026-03-15 起降为 200 天,2027-03-15 起 100 天,2029-03-15 起 47 天。因此必须配置自动续期。

「不校验合法域名」开关只对模拟器生效,真机预览、体验版和正式版一律按正式规则校验。真机联调只能先把域名配进后台白名单,或在体验版中开启开发调试模式查看日志。