Skip to content

Taro dev 环境 prebundle 路径异常

text
环境:
    react: ^18.0.0
    react-dom: ^18.0.0
    taro-ui: ^3.1.1
    @tarojs/taro: 3.6.18
    Node.js: v18.17.0

1. 症状

npm run dev:weapp 启动后,微信开发者工具报错:

Taro 开发环境 prebundle 路径异常排查 配图 1

错误指向 JS 文件加载失败。检查 app 入口文件的编译产物:

Taro 开发环境 prebundle 路径异常排查 配图 2

编译产物被放在 prebundle 目录下,但入口文件中的 require 路径缺少 prebundle/ 前缀,导致模块解析失败。

2. 排查过程

2.1 预编译模式

Taro 官方文档提到:

Taro 开发环境 prebundle 路径异常排查 配图 3

开发环境默认开启预编译(prebundle),将第三方依赖提前打包进 prebundle 目录以减少重复编译。

入口文件中被 prebundle 的依赖,引用路径应该带 prebundle/ 前缀。实际产物中前缀丢失——说明 webpack 的模块解析在某个阶段出了问题。

2.2 关闭预编译后仍然失败

按理说关掉 prebundle 后走普通编译流程,路径问题应该消失。但实际关闭后微信开发者工具依然报错找不到 JS 文件,而目录下文件确实存在:

Taro 开发环境 prebundle 路径异常排查 配图 4

重启开发者工具后恢复正常。

Taro 开发环境 prebundle 路径异常排查 配图 5

这个现象说明问题不只在路径前缀本身,微信开发者工具的文件监听 / 自动更新机制与 Taro 的 watch 编译之间也存在时序差异。编译产物写入磁盘后,工具的文件变更检测可能滞后或未触发,最终运行的仍然是旧的产物缓存。

2.3 Webpack 版本线索

排查过程中,社区里也有人提到 Webpack5 → Webpack4 的降级路径:

Taro 开发环境 prebundle 路径异常排查 配图 6

Taro 3.6 默认使用 Webpack5,但 Webpack5 的 output.clean / asset module / splitChunks 等默认行为与 Webpack4 存在差异。prebundle 作为预编译环节,产物的输出路径依赖于 webpack 的 output.path + output.publicPath 配置组合。如果 Taro 在 Webpack5 下对 prebundle 产物路径的处理有未覆盖的边界(比如 __webpack_public_path__ 的注入时机),就会表现为前缀丢失。

不过降级到 Webpack4 更像是绕过问题,而不是定位根因。Webpack4 下 prebundle 的处理逻辑可能走了不同的代码分支,只是刚好避开了这一异常。

2.4 平台差异

另一个线索是不同平台的编译产物不一致:

Taro 开发环境 prebundle 路径异常排查 配图 7

Taro 多平台的编译入口确实有差异——weapp、swan、alipay 各自对应不同的 webpack config 和插件。如果 prebundle 的路径前缀问题只在 weapp 平台出现,那问题大概率出在 @tarojs/plugin-platform-weapp 或 weapp 平台专属的 webpack chain 中。

3. 当前状态

尚未定位到明确的配置缺陷或代码 bug。

当前可行的临时规避方案是关闭预编译(prebundle: false),并配合开发者工具重启。

js
// config/dev.js
module.exports = {
  compiler: {
    prebundle: false
  }
}

后续需要最小复现来隔离变量——创建一个干净的 Taro 3.6.18 项目,逐步添加依赖和配置,确认 prebundle 路径前缀丢失的复现条件。