这篇记录来自一个真实项目：一套基于 uni-app 的微信小程序源码，后端是 WordPress。代码本身能跑，但换到自己服务器之后，从「编译不过」一路踩到「首页白屏」，中间有四个坑，每个坑的表现都和真实原因相距很远。记下来给同样在折腾的人。
一、接口域名藏在编译产物里
最容易被忽略的一点：小程序里的接口地址不是配置项，而是硬编码在源码里的常量。
// components/api.js
export const API = 'https://www.example.com/';
export const Getfriend = API + '/wp-content/plugins/xxx/friend.php';这意味着换域名不是改后台设置，而是改代码。更隐蔽的是，如果常量结尾带 /，拼接时又加一个 /，实际请求就会变成 https://host//wp-json/... —— 多数服务器能容忍，但一旦遇到严格的网关就会 404。
我的处理是把结尾的斜杠去掉，让所有调用统一成 API + '/wp-json/...'，一处改动修掉全部双斜杠。
二、首页白屏的真正原因：配置接口返回空数组
页面结构、样式、路由都正常，但界面一片空白。打开网络面板，看到的是这样一行：
GET /wp-json/wp/v2/fengrui → 200 []
长度 = 2 个字符：[ ]而这个接口返回的配置对象，在代码里被当成必定存在的数据使用：about_center[0].share_title、about_center[0].index_style……全项目一共 89 处直接下标取值。数组为空，就等于每一处都是 undefined，页面自然什么都不显示。
排查后发现 fengrui 并不是插件注册的路由，而是一个自定义文章类型的 rest_base：
about : 基本配置 (rest_base = fengrui)也就是说，后台需要有一条「基本配置」记录并已发布，接口才有内容。草稿状态不会出现在 REST 里 —— 这一点看着理所当然，实际排查时卡了很久。
经验：远程配置驱动的页面，一定要给配置加兜底。哪怕只是一个空对象和一个「配置缺失」的提示，也比整页白屏好排查得多。
三、一个看不见的 BOM 挡住了编译
用脚本改完 manifest.json（去掉 JSON 注释）之后，编译直接报错：
Error: manifest.json解析失败，不符合 json 规范
Unexpected token '', "{ "n"... is not valid JSON那个看起来空空的字符，就是 UTF-8 BOM（EF BB BF）。Windows 上某些写法会默默把它写进文件头，而 JSON.parse 不接受它。检查方法很简单：
format-hex manifest.json | select -first 1修复则是用不带 BOM 的方式重写：
# 错误：PowerShell 5.1 的 Encoded utf8 会写入 BOM
Set-Content manifest.json -Encoding utf8
# 正确：显式指定无 BOM
[IO.File]::WriteAllText($path, $text, (New-Object Text.UTF8Encoding($false)))四、模拟器启动失败，其实是进程残留
编译通过、工具也拉起来了，结果控制台弹出：
Error: simulator launch failed这看起来像项目问题，实际和项目无关。微信开发者工具的模拟器是作为一个本地服务启动的（日志里能看到 http://127.0.0.1:41830/native/...）。如果上一轮没有完全退出，就会有新旧两代进程同时存在，抢同一个端口，新实例的模拟器自然起不来。
验证方式：任务管理器里看「微信开发者工具」是不是有一批进程，而启动时间分成两段。
解决办法只有一个：把工具彻底退出，确认进程清零，再重新打开。反复点「运行」只会叠加更多实例。
写在最后：这次总结出的排查顺序
- 先看接口：打开
/wp-json/和自定义路由，确认返回的是数据还是[] - 再看编译：能从源码编译出
app.json，说明工程本身没问题 - 然后看工具：编译产物完整但模拟器报错，先怀疑进程残留和端口占用
- 最后看环境：域名、证书、合法域名白名单 —— 小程序强制 HTTPS，这一条不满足，前面全白搭
四个坑里，只有一个真正属于「代码」，其余三个都是环境和流程。这也是为什么排查时先问「哪一层出的错」，比直接读源码有效得多。
发表回复