从零把 uni-app 接到微信开发者工具：HBuilderX 全流程与踩坑复盘

这篇写给后端同学：不懂前端也能把 uni-app 项目跑到微信开发者工具里预览页面。

核心结论先说：

• uni-app 源码目录不能直接当小程序目录导入微信开发者工具。
• 必须先用 HBuilderX 编译，拿到 unpackage/dist/build/mp-weixin 产物。
• 再让微信开发者工具打开这个产物目录（或通过 project.config.json 的 miniprogramRoot 指过去）。

先分清 3 个 appid（这是第一大坑）

1. 微信小程序 appid（wxa...）
   • 用于微信开发者工具和小程序平台。
2. DCloud appid（__UNI__...）
   • 在 manifest.json 里，HBuilderX 编译/发行会校验它。
3. 项目目录里的 project.config.json appid
   • 微信开发者工具读取的配置。

很多报错看起来像“编译问题”，本质是 appid 权限问题。

最短可跑通流程（推荐）

1) 安装 HBuilderX

brew install --cask hbuilderx

2) 在 HBuilderX 导入项目

打开 HBuilderX，导入 factory-miniprogram 项目根目录。

3) 登录 DCloud 账号，并完成手机号绑定

否则会出现：

• 此功能需要先登录
• 当前账号尚未绑定手机号

4) 在 manifest.json 里确认 DCloud appid 可用

如果看到：

• 您不是这个应用的项目成员

需要在 HBuilderX 的 manifest.json 可视化界面点击“重新获取”，拿到你账号下可用的 __UNI__...。

5) 本地编译到微信小程序（不上传）

可以用 HBuilderX 菜单操作，也可以用 CLI：

/Applications/HBuilderX.app/Contents/MacOS/cli publish mp-weixin \
  --project /你的项目绝对路径/factory-miniprogram \
  --name factory-miniprogram \
  --appid 你的微信appid \
  --upload false

成功后会看到类似输出：

• 导出微信小程序成功，路径为：.../unpackage/dist/build/mp-weixin

在微信开发者工具里预览

目标目录：

/Users/.../factory-miniprogram/unpackage/dist/build/mp-weixin

两种方式都行：

1. 直接在微信开发者工具导入这个目录。
2. 导入项目根目录，并在 project.config.json 设置：

"miniprogramRoot": "unpackage/dist/build/mp-weixin",
"srcMiniprogramRoot": "unpackage/dist/build/mp-weixin"

这次真实踩坑清单（报错 -> 原因 -> 处理）

坑 1：app.json: 在项目根目录未找到 app.json

• 原因：把 uni-app 源码目录直接当小程序目录导入。
• 处理：先编译，导入 unpackage/dist/build/mp-weixin。

坑 2：component not found ... u-input

• 原因：之前编译不完整/失败，uni_modules 没有正确产出。
• 处理：修复编译阻塞后重新导出，确认存在：
  • unpackage/dist/build/mp-weixin/uni_modules/uview-ui/components/u-input/*

坑 3：此功能需要先登录

• 原因：HBuilderX CLI 的发布能力依赖 DCloud 登录态。
• 处理：登录 DCloud 账号。

坑 4：尚未绑定手机号

• 原因：账号安全策略限制。
• 处理：在 DCloud 用户中心绑定手机号。

坑 5：您不是这个应用的项目成员

• 原因：manifest.json 中 __UNI__... 不属于当前账号。
• 处理：在 manifest.json 中“重新获取” DCloud appid。

坑 6：代码使用了 scss/sass 语言，但未安装相应编译器插件

• 原因：缺少 compile-dart-sass 编译插件。
• 处理：安装后重新编译。

坑 7：微信开发者工具自动拉起失败（IDE Service Port）

• 原因：微信开发者工具 CLI 服务端口未就绪。
• 处理：这不影响手动导入预览，直接在微信开发者工具里手动打开产物目录即可。

给后端同学的“最小心智模型”

把链路记成 3 步就够了：

1. uni-app 源码（不能直接预览）
2. HBuilderX 编译（生成小程序产物）
3. 微信开发者工具打开产物

只要第 2 步成功，前后端联调就能开始。

建议固定成团队 SOP

1. 新同学先登录并绑定 DCloud 账号。
2. 项目初始化第一天就重新获取可用 __UNI__...。
3. project.config.json 固化 miniprogramRoot 到 unpackage/dist/build/mp-weixin。
4. 联调前先检查导出目录下是否有：
   • app.json
   • uni_modules/uview-ui/components/u-input/*

这四条能省掉 80% 的环境问题排查时间。