HBuilderX 改了 uni-app 代码后，怎么在微信开发者工具里看到更新

这篇整理一次最近联调 uni-app 小程序时连续踩到的几个坑：

  • 改了 accountPage.vue 和 pages.json，微信开发者工具里就是看不到更新
  • HBuilderX 运行到微信开发者工具时，微信侧没有自动拿到最新项目
  • 登录时报错：
1
login:fail 系统错误，错误码：41002, appid missing [undefined]
  • 本机 Java 服务联调时报错：
1
http://127.0.0.1:19002 不在以下 request 合法域名列表中

如果你也遇到“源码有 diff，但微信里没变化”“wx.login 报 appid missing”或者“本机接口被合法域名拦住”这几个问题，可以直接按这篇处理。

先说结论

核心结论其实只有 5 条：

  1. uni-app 改的是源码，不是微信开发者工具直接运行的产物
  2. 改完代码后，要先在 HBuilderX 重新编译
  3. 微信开发者工具最好先打开 服务端口
  4. 如果要在微信开发者工具里直连本机接口，先打开 开发环境不校验请求域名、TLS 版本及 HTTPS 证书
  5. 如果微信开发者工具里项目详情的 AppID 显示为空，关键是 把 AppID 补进去

为什么改了源码，微信开发者工具里没变化

uni-app 项目最容易让人误判的一点是：

  • 你改的是源码目录
  • 微信开发者工具跑的是编译后的目录

像这类项目，project.config.json 一般会这样配置：

1
2
3
4
{
  "miniprogramRoot": "unpackage/dist/build/mp-weixin",
  "srcMiniprogramRoot": "unpackage/dist/build/mp-weixin"
}

这表示微信开发者工具实际读取的是：

1
unpackage/dist/build/mp-weixin

而不是项目源码根目录。

所以只改：

  • pages/tabPages/accountPage.vue
  • pages.json

还不够。
必须让 HBuilderX 重新把源码编译到 unpackage/dist/build/mp-weixin，微信开发者工具才会看到。

正确联调顺序

把整条链路记成下面这句就够了：

1
改 uni-app 源码 -> HBuilderX 重新编译 -> 微信开发者工具读取新产物 -> 页面更新

也就是说：

  • HBuilderX 负责编译
  • 微信开发者工具 负责运行和预览

第一步：在微信开发者工具里打开服务端口

如果你想让 HBuilderX 更顺畅地联动微信开发者工具，先做这一项。

操作路径：

  1. 打开微信开发者工具
  2. 点击顶部菜单 设置
  3. 进入 安全设置
  4. 打开 服务端口

不同版本的微信开发者工具文案可能略有差异，但关键词基本就是：

  • 安全设置
  • 服务端口

这一步的作用是让外部工具更容易和微信开发者工具交互。

不开时常见现象：

  • HBuilderX 运行到微信开发者工具失败
  • HBuilderX 编译了，但微信开发者工具没正常联动
  • 需要手动回到微信开发者工具里重新打开项目

第二步：在 HBuilderX 重新编译

改完代码后，在 HBuilderX 执行：

  1. 打开项目根目录
  2. 点击 运行
  3. 选择 运行到小程序模拟器
  4. 选择 微信开发者工具

这一步会做两件事：

  • 把 uni-app 源码重新编译成微信小程序代码
  • 输出到 unpackage/dist/build/mp-weixin

如果你只是想验证编译是否真的发生了，直接看这个目录有没有更新：

1
unpackage/dist/build/mp-weixin

特别关注：

  • app.json
  • pages/tabPages/accountPage.*
  • 你新增页面对应的目录和文件

第三步：回到微信开发者工具重新编译

HBuilderX 编译完后，再回微信开发者工具做一次刷新。

建议动作：

  1. 点顶部 编译
  2. 如果还没变化，再点一次 清缓存并编译

很多时候问题不在代码，而是微信开发者工具还停留在旧产物。

这次新增踩坑：本机 Java 服务被合法域名拦住

联调本地 Java app 时，这次还遇到了这个报错：

1
http://127.0.0.1:19002 不在以下 request 合法域名列表中

这不是后端接口本身坏了，而是微信开发者工具默认会校验请求域名。

如果只是为了在本机开发阶段联调自己电脑上的服务，最直接的处理方式是：

  1. 打开微信开发者工具
  2. 点击右上角 详情
  3. 进入 本地设置
  4. 打开 开发环境不校验请求域名、TLS版本及HTTPS证书
  5. 回到项目重新编译

开完这一项后，开发者工具里的模拟器就可以直接请求：

1
http://127.0.0.1:19002/mock-service

这里还要补一个边界：

  • 这适合 微信开发者工具本机联调
  • 不适合 真机用 127.0.0.1 联调

因为对手机来说，127.0.0.1 指向的是手机自己，不是你电脑。

如果要真机联调，应该改成你电脑的局域网 IP，比如：

1
http://<你的局域网IP>:19002/mock-service

同时保证：

  • 手机和电脑在同一个局域网
  • Java 服务监听的是外网可访问地址，而不是只绑定 127.0.0.1
  • 本机防火墙放通 19002

这次新增踩坑：登录失败，报 appid missing

这次另一个非常典型的问题是：

1
login:fail 系统错误，错误码：41002,appid missing [undefined]

这个报错说明的不是“后端登录接口坏了”，而是：

当前微信开发者工具运行的这个项目实例，没有拿到有效的微信小程序 AppID。

报错里的关键信息是：

  • appid missing
  • [undefined]

本质上就是当前项目运行时 AppID 是空的。

怎么确认是不是 AppID 为空

在微信开发者工具里：

  1. 打开当前项目
  2. 点击右上角 详情
  3. 看 基本信息
  4. 找 AppID

正常情况下，这里应该显示一个真实的小程序 AppID，比如：

1
<示例微信小程序AppID>

如果这里显示的是：

  • 空
  • undefined

那 wx.login 基本一定会失败。

为什么源码里明明配了 AppID，微信里还是空

这是最容易误判的地方。

项目源码里可能已经配置了：

  • manifest.json 里的 mp-weixin.appid
  • project.config.json 里的 appid

但如果你在微信开发者工具里打开的是一个旧项目实例，或者当前项目配置没有正确带上 AppID，微信开发者工具当前运行的项目依然可能是“无 AppID”状态。

也就是说：

源码配对了，不代表当前微信开发者工具里的运行实例就一定对。

这次实际有效的解决方法

这次最后能跑通，关键动作是：

把微信开发者工具当前项目里的 AppID 补上。

这次实际操作里，最终不需要重新手动导入项目，直接把 AppID 填进去就好了。

更准确的处理顺序应该写成：

  1. 关闭微信开发者工具里当前旧项目
  2. 从项目列表删除旧项目
  3. 在 HBuilderX 先重新编译一次
  4. 回到微信开发者工具，确认当前项目详情里的 AppID 是否为空
  5. 如果为空，直接在对应项目配置里 手动填写 AppID
  6. 再重新编译并测试登录

这一步之后，再看项目详情里的 AppID，如果已经不是空值，wx.login 就能正常工作。

如果 HBuilderX 和微信开发者工具之间的项目联动已经正常，通常补完 AppID 就够了，不必额外手动导入。

一个特别重要的细节

也不要想当然地觉得：

HBuilderX 已经编译过了，微信开发者工具肯定会自动继承 AppID。

实际踩下来，不少时候它不会。

真正关键的不是“是否重新导入”，而是：

  • HBuilderX 负责编译
  • 微信开发者工具当前运行项目里必须有正确的 AppID

手动导入 unpackage/dist/build/mp-weixin 只是一个兜底方案，不是这次问题的必要步骤。

推荐固定成团队 SOP

如果团队里有后端同学或者不常碰小程序的同学，建议直接固定成以下流程：

  1. 修改 uni-app 源码
  2. 微信开发者工具开启 服务端口
  3. 如果要连本机接口，先在 详情 -> 本地设置 里打开 开发环境不校验请求域名、TLS版本及HTTPS证书
  4. 回 HBuilderX 执行 运行 -> 运行到小程序模拟器 -> 微信开发者工具
  5. 确认 unpackage/dist/build/mp-weixin 已更新
  6. 微信开发者工具里重新编译
  7. 如果登录报 appid missing
  8. 先去项目详情检查 AppID 是否为空
  9. 如果为空，直接补上正确的 AppID
  10. 再重新编译并验证登录
  11. 只有前面还不行时，再考虑手动导入 unpackage/dist/build/mp-weixin

最后一条经验

这类问题很容易让人往“接口错了”“前端没改对”“缓存没清”这些方向排查很久。

但真正高频的根因其实就两个：

  1. 没重新编译
  2. 微信开发者工具当前运行实例的 AppID 是空的

如果还在本机联调后端，再加一个高频原因：

  1. 微信开发者工具没有关闭开发环境的域名校验

一句话总结：

uni-app 联调时，先确认产物有没有重新生成，再确认微信开发者工具里当前项目的 AppID 不是空；如果要连本机服务，还要先关闭开发环境域名校验。补 AppID 是关键，手动导入只是备选。

#uni-app #微信小程序 #HBuilderX #微信开发者工具 #联调
HBuilderX 改了 uni-app 代码后，怎么在微信开发者工具里看到更新
https://willfordzhan.github.io/2026/03/03/hbuilderx-uni-app/
作者
詹文杰
发布于
2026年3月3日
许可协议