微信小程序 web-view 打开空白或提示未配置业务域名：校验文件、HTTPS 与跳转域名排查

典型现象：开发者工具里 <web-view src="https://..."> 能打开 H5，真机预览或体验版却是白屏；有的直接弹「域名未配置」；有的能闪一下标题栏，内容区一直空。

web-view 走的是业务域名 ，不是 request 合法域名。两边配齐了仍白屏时，多半是校验文件没落到正确路径、证书链不完整，或 H5 自己又跳到了未登记的二级域名。下面按「先分清域名类型 → 再核校验文件 → 再查证书与跳转」走。

0. 先确认是不是 web-view，以及报错原文

页面里确认用的是：

xml 复制代码

<!-- pages/h5/h5.wxml -->
<web-view src="{{url}}"></web-view>

js 复制代码

// pages/h5/h5.js
Page({
  data: { url: 'https://h5.example.com/order?id=1' },
  onLoad(q) {
    if (q.url) this.setData({ url: decodeURIComponent(q.url) })
  }
})

真机打开调试（右上角 ··· → 开发调试 → 打开调试），看是否出现类似文案：

提示片段	优先怀疑
未配置业务域名 / not in business domain	管理后台业务域名未加、未发布生效
校验文件 / check file	`MP_verify_*.txt` 路径或内容不对
SSL / certificate / TLS	证书链缺中间证、过期、SNI 不对
空白但无报错	H5 内部又跳到了未登记域名，或被 CSP / X-Frame 拦

注意：开发者工具勾了「不校验合法域名...」时，业务域名校验也会被放过。排查前务必取消勾选，在电脑上先复现。

1. 业务域名 ≠ request 合法域名

位置：小程序管理后台 → 开发管理 → 开发设置 → 服务器域名。

request 合法域名 ：给 wx.request / wx.uploadFile 等用；
业务域名 ：给 <web-view> 用，单独一张表。

逐条核业务域名：

只填域名（可带 https:// 前缀按后台提示），不要带路径、端口、query；
h5.example.com 与 example.com 是两个域名，H5 实际打开哪个就配哪个；
每月修改次数有限，改完点保存后等几分钟再真机测，不要连续猛改；
个人主体与部分类目对业务域名有额外限制，后台若灰掉「业务域名」入口，先看类目与认证状态，而不是反复清缓存。

src 必须是 https://。http://、IP、localhost、带端口的内网地址在真机上都会失败。

2. 下载校验文件并落到「可直链访问」的路径

后台给每个业务域名提供一个校验文件，例如 MP_verify_xxxxxxxx.txt。要求：

文件内容与后台完全一致（多空格、换行、BOM 都会挂）；
通过 https://你的业务域名/MP_verify_xxxxxxxx.txt 浏览器无登录即可打开，返回纯文本；
不要放到需要登录、需要 Cookie、被 301 到登录页的路径下。

常见翻车点：

站点是 SPA，所有路径被前端路由吃掉，校验文件返回了 index.html；
Nginx / CDN 把 .txt 也套了鉴权或 WAF 挑战页；
文件放在 https://www.example.com/...，业务域名却配的是 h5.example.com。

Nginx 可单独放行（路径按实际改）：

nginx 复制代码

location = /MP_verify_xxxxxxxx.txt {
    default_type text/plain;
    add_header Cache-Control "no-store";
    alias /var/www/h5/MP_verify_xxxxxxxx.txt;
}

用命令确认（应看到文件原文，且 HTTP 200）：

bash 复制代码

curl -sSI "https://h5.example.com/MP_verify_xxxxxxxx.txt"
curl -sS  "https://h5.example.com/MP_verify_xxxxxxxx.txt"

curl -sSI 里若出现 302 到登录页或 content-type: text/html，按上面逐项改，直到是 text/plain（或至少 body 就是校验串）。

后台点「校验」通过后，再保存业务域名。校验没过就保存，真机一定白屏。

3. HTTPS 证书链与 TLS

业务域名必须是完整、可信的 HTTPS。本机浏览器能打开不等于小程序 WebView 能过：部分环境对中间证书缺失更敏感。

bash 复制代码

# 看证书链是否完整、是否过期
echo | openssl s_client -connect h5.example.com:443 -servername h5.example.com 2>/dev/null | openssl x509 -noout -dates -subject -issuer

重点看：

证书 CN/SAN 是否包含你配置的业务域名；
是否缺中间证（常见于只上传了站点证、没上传 chain）；
是否仅支持过旧或过新的 TLS，导致部分机型握手失败。

CDN / 对象存储做静态托管时，把「强制 HTTPS」和「完整证书链」打开后再测 web-view。

4. H5 内部跳转与二级域名

即使入口 https://h5.example.com/order 已在业务域名里，页面里若再：

location.href = 'https://pay.example.com/...'
或跳到 https://example.com/login（裸域未登记）

WebView 仍会白屏或中断。处理方式：

所有会被打开的主机名都进业务域名表；或
把登录 / 支付页收敛到同一业务域名下的路径；或
必须出域的流程改用小程序原生页 + wx.request，不要在 web-view 里硬跳。

排查时在 H5 里临时打日志，或用真机调试看最终 document URL 落在哪个 host。

5. 被嵌入策略挡住（相对少见，但要会查）

若业务域名、校验、证书都过了，内容仍空，在 H5 响应头里查：

bash 复制代码

curl -sSI "https://h5.example.com/order" | tr -d '\r' | grep -iE 'x-frame-options|content-security-policy'

X-Frame-Options: DENY / SAMEORIGIN 可能阻止被小程序 WebView 嵌入；
CSP 里 frame-ancestors 若过严，同样会空白。

按业务需要放宽到允许被微信 WebView 加载（具体值以安全策略为准，不要无脑 *）。改完清 CDN 缓存再测。

6. 验证清单（做完打勾）

开发者工具已关闭「不校验...」，电脑上能复现或已通过；
src 为 https://，主机名与后台业务域名一致（不是 request 合法域名）；
https://业务域名/MP_verify_xxx.txt 可匿名访问且内容匹配；
后台业务域名校验通过并已保存；
证书链完整、未过期；
H5 全程不跳到未登记域名；真机预览 / 体验版能稳定出页面。

个人开发阶段可先用「业务域名」配测试域；上线前换成正式域并重新走校验，避免体验版正常、正式版因域名表不一致再白一次。

本文由 DEVDIY 整理。我们平时主要做 WordPress / Shopify 外贸站和微信小程序的开发与线上排查，把 web-view 这类「工具里正常、真机空白」的问题拆成可复现的步骤。

原文／延伸阅读：https://devdiy.cn/miniprogram/