陈年老查的博客

分类： 小程序开发

  • uni-app 微信小程序对接 WordPress：一次完整的踩坑排查记录

    这篇记录来自一个真实项目：一套基于 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/...）。如果上一轮没有完全退出，就会有新旧两代进程同时存在，抢同一个端口，新实例的模拟器自然起不来。

    验证方式：任务管理器里看「微信开发者工具」是不是有一批进程，而启动时间分成两段。

    解决办法只有一个：把工具彻底退出，确认进程清零，再重新打开。反复点「运行」只会叠加更多实例。

    写在最后：这次总结出的排查顺序

    1. 先看接口：打开 /wp-json/ 和自定义路由，确认返回的是数据还是 []
    2. 再看编译：能从源码编译出 app.json，说明工程本身没问题
    3. 然后看工具：编译产物完整但模拟器报错，先怀疑进程残留和端口占用
    4. 最后看环境：域名、证书、合法域名白名单 —— 小程序强制 HTTPS，这一条不满足，前面全白搭

    四个坑里，只有一个真正属于「代码」，其余三个都是环境和流程。这也是为什么排查时先问「哪一层出的错」，比直接读源码有效得多。