开发者工具里模拟器一切正常，一点「真机预览」却整页白屏，或控制台刷出 request:fail url not in domain list、tls handshake、ERR_CONNECTION------有的页面能开一半、网络请求全挂。这和今天已写过的「登录后跳回登录页（Cookie / CDN）」「Elementor 编辑器空白」「前台 502/503（PHP-FPM）」「白屏 / 严重错误（Fatal / 插件二分）」「Shopify 结账按钮灰色」「WP-Cron 定时不准点」「媒体库上传失败」「固定链接改文章名后全站 404」不是一类故障：那些卡在 WordPress / Shopify 的会话、编辑器资源、网关、PHP、结账脚本、Cron、上传或 rewrite；这里卡在 微信小程序运行时------request 合法域名、TLS / 证书、体验版与开发版缓存、隐私权限声明、基础库与条件编译。
更稳的顺序是：先分清是 合法域名未配 / TLS 或未备案域名 / 体验版缓存脏 / 权限与隐私未声明 / 基础库或代码路径问题 → 到公众平台核对服务器域名（request / uploadFile / downloadFile / socket）→ 确认 HTTPS、TLS1.2+、信任证书与 ICP → 删小程序重进体验版并对照开发版 / 正式版 → 再查 app.json 权限与隐私协议 → 最后用真机调试看 Network / Console。别一上来就重写整页，也别以为「开发者工具勾了不校验合法域名」真机也会放过。
很多项目在换 API 域名、迁 HTTPS、提体验版、或刚加地理位置 / 相册权限之后才「突然」真机白屏：模拟器仍绿，真机却空白或 request 全 fail。根因通常不在「页面写坏了」，而在 真机走的是正式校验链路------域名白名单、证书链、体验成员与本地缓存和工具里的宽松模式根本不是同一套规则。
先分清：合法域名 / TLS / 体验版缓存 / 权限隐私 / 基础库与代码
「真机预览白屏或 request 失败」常见落在五条线上，别和 WordPress 白屏、502、Shopify 结账混着改：
- 合法域名未配 / 配错 ：公众平台「开发管理 → 开发设置 → 服务器域名」里
request合法域名未加、少了子域、多了路径、或写成了http://；本地「详情 → 本地设置 → 不校验合法域名」仅开发者工具有效，真机预览 / 体验版一律按线上名单校验。 - TLS 或未备案域名：接口仍是明文 HTTP、自签证书、过期证书、仅支持 TLS1.0、或域名未备案 / 未接入合法 HTTPS------真机直接拒绝握手，表现常是白屏 + Network 里 request fail。
- 体验版 / 开发版缓存脏：旧包残留、扫码人不是体验成员、开发版与体验版代码不同步；删不掉小程序、清不掉存储时会「修了代码真机还是旧行为」。
- 权限与隐私接口未声明 ：
app.json未声明所需 scope，或未配置隐私协议弹窗；用户拒绝定位 / 相册后页面无兜底，看起来像白屏。 - 基础库或代码条件编译问题 ：真机基础库低于项目最低版本；
#ifdef/ 分包路径 / 插件引用在工具能解析、真机进不了入口页。
另记易混项：仅某一页白、其它页正常 → 优先查该页 onLoad 里的首个 request 与域名；所有 request 都 fail、静态页能开 → 几乎肯定是合法域名 / TLS；仅某个体验成员白屏 → 查是否在体验成员列表、是否扫到了旧二维码。
第一步：公众平台核对 request 合法域名 ------ 真机不认「不校验」
用管理员打开 微信公众平台 → 开发管理 → 开发设置 → 服务器域名：
- 核对 request 合法域名 、uploadFile 合法域名 、downloadFile 合法域名 、socket 合法域名 是否分别包含你真实调用的主机名（只填域名，不要带
https://路径或端口以外的多余段；按控制台当前规则填写）。 - 子域要显式添加：
api.example.com与example.com不是一回事；CDN 回源域名、对象存储下载域名若被wx.request/wx.downloadFile打到，也要进对应名单。 - 改完域名后，开发者工具里重新编译，真机再扫一次预览码；名单有缓存窗口，刚保存立刻扫有时仍吃旧配置，隔一两分钟再试。
- 本地「不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书」勾选 只作用于模拟器 / 开发者工具。真机预览、体验版、正式版都会校验------这是「工具正常、真机全挂」的第一高频原因。
预期定界：
- 补域名后真机 request 立刻 200 → 定界在合法域名；
- 域名已齐仍 fail → 进第二步看 TLS / 证书 / 备案；
- 仅 upload / download 失败 → 查对应名单是否漏配，而不是只盯 request。
第二步：HTTPS、TLS1.2+、信任证书与 ICP
真机对证书比开发者工具严得多：
- 接口必须是 HTTPS ；
http://明文在真机基本直接失败（工具勾了不校验时还能「假装成功」）。 - 服务端支持 TLS1.2 及以上；过老的网关 / 自建 Nginx 只开 TLS1.0 时，真机握手失败，errMsg 里常带 tls / ssl 字样。
- 证书须由系统信任的 CA 签发；自签、过期、域名与证书 CN/SAN 不符、中间证书链不全------浏览器桌面也许还能点「继续」，小程序真机不会。
- 境内主体还要确认域名 ICP 备案 与小程序类目要求匹配；未备案或备案主体不一致时，有时能配进名单但真机访问被拒。
- 用桌面
curl -vI https://你的api域名/看握手与证书链；再用真机调试的 Network 对照同一 URL，避免只看工具里的绿色勾。
域名、证书、备案与发布侧配置搅在一起时，可对照 小程序域名与发布侧排查 的分层思路，先定界是「名单没写上」还是「写上了但 TLS / 备案过不了」，再决定改公众平台还是改网关。
第三步：体验版缓存、删小程序、成员与三端对照
域名和证书都过了，真机仍白或仍跑旧逻辑时：
- 手机上 删除小程序 （长按 → 删除），清掉本地包与部分缓存，再扫 当前 体验版 / 预览码进入。
- 对照三条通道：开发版（预览） 、体验版 、正式版------确认扫的码、后台选的版本、CI 上传的版本号一致；常见事故是改了开发版、体验版还是昨天的包。
- 确认扫码人在 成员管理 → 体验成员（或项目成员）列表里；不在列表时有的机型表现为进不去，有的表现为空白页。
- 开发者工具「清缓存 → 全部清除」后再编译上传；真机侧可在「微信 → 设置 → 通用 → 存储空间」里对小程序存储做清理（路径因微信版本略有差异）。
- 仍异常时开 真机调试，看 Console 是否还有旧域名、旧路由或缓存的 token 指向已下线环境。
预期：删小程序 + 重新扫当前体验码后恢复 → 多半是脏缓存或旧包；三端表现不一致 → 先对齐上传版本，而不是改业务代码。
第四步：app.json 权限、隐私协议与 scope 兜底
页面 onLoad 就调定位、相册、通讯录、蓝牙等接口时：
- 检查
app.json（及页面 json）是否声明了所需权限字段；缺声明时真机可能直接失败，工具里有时仍能 mock 成功。 - 按当前平台规则配置 用户隐私保护指引 / 隐私协议弹窗；未配置就调隐私接口，真机可能中断引导流，表现成首屏白。
- 用户点「拒绝」后，业务是否有兜底 UI------若拒绝后仍假设「一定有 lat/lng」去渲染地图或列表，就会白屏或卡在 loading。
- 真机调试看授权弹窗是否出现、
wx.getSetting里对应 scope 状态；把「未声明 / 未弹窗 / 已拒绝无兜底」分开处理。
预期：补齐声明与隐私配置后首屏能出；拒绝路径有占位或引导，不再整页空白。
第五步：基础库、条件编译、分包路径与真机调试
- 开发者工具「详情 → 本地设置」看调试基础库；真机微信版本对应的基础库若 低于 项目
requiredBackgroundModes/ 最低基础库要求，新 API 会挂，严重时入口都进不去。 - 条件编译（如多端框架的
#ifdef MP-WEIXIN）导致真机入口组件被裁掉；工具用另一套编译参数时不容易发现------以真机调试的 AppData / WXML 是否挂载为准。 - 分包根路径、插件 provider、独立分包预下载配置写错时，工具可能仍能打开主包页，真机跳进分包就白。
- 打开 真机调试 ：Network 看失败请求的 URL 是否在合法域名内、状态码与 TLS；Console 看是否有
is not in domain list、privacy、component not found、基础库相关报错。 - 一次只改一层：先域名，再证书，再版本缓存，再权限，最后才动大段业务代码------否则无法定界。
常见误操作（尽量避开）
- 工具里勾了「不校验合法域名」就上体验版------真机不认这勾，白屏会原样出现在客户手机上。
- 合法域名写成带路径的 URL，或漏了 uploadFile / downloadFile 名单，只配了 request。
- 接口仍是 HTTP 或自签证书，却在业务群里怪「小程序又抽风」。
- 改完代码不上传体验版、不删手机端小程序，反复扫旧码验新逻辑。
- 隐私接口未声明就强依赖定位渲染首屏，用户一拒绝就白屏，还当成「真机预览 bug」。
- 同时改域名、证书、基础库、分包路径四项------维护窗口建议一次只动一层并保留上一体验版可回滚。
验收清单（无软广，只验结果）
同一轮真机验证建议勾完下面几项再收工：
- 公众平台 request / uploadFile / downloadFile / socket 合法域名已含真实调用主机；工具里「不校验」仅作本地开发，真机未依赖该勾选。
- 接口全程 HTTPS，TLS1.2+，证书链完整且域名匹配；
curl与真机 Network 对同一 URL 无握手错误。 - 删除小程序后重扫 当前 体验版 / 预览码；扫码人在体验成员列表；开发版 / 体验版 / 正式版版本号已对齐。
app.json与隐私指引覆盖所用接口；拒绝授权有兜底，首屏不再因 scope 空白。- 真机基础库 ≥ 项目要求；分包 / 插件路径在真机调试下可进入；Console 无 domain list / tls / privacy 类未处理错误。
- 变更可回滚：保留上一体验版包、域名变更记录、证书到期日备注，出问题能单条撤回。
把「合法域名 → TLS / 证书 → 体验版缓存与成员 → 权限隐私 → 基础库与真机调试」按顺序走完，大多数「真机预览白屏 / request 失败」会落在前三步之内。与今天的 WordPress 登录 Cookie、Elementor、502、Fatal、Shopify 结账、WP-Cron、媒体上传、固定链接 404 分界清楚，就不必在错误层重写整站业务页。