记一次因 vue-router 升级而导致的 uniapp 故障
因
vue-router在4.6.0版本使用了tsup重构打包行为，使得dist文件夹缺少vue-router/dist/vue-router.esm-bundler.js文件，进而导致uniapp的 H5 打包失败
在云端复现故障
问题起因，在 github workflow 流水线打包的项目出现莫名其妙的故障，称找不到 vue-router.esm-bundler.js 文件。
如下图所示，缺少 vue-router/dist/vue-router.esm-bundler.js 导致的错误。
[commonjs--resolver] Cannot find module '/home/runner/work/001-Smart-Community/001-Smart-Community/node_modules/vue-router/dist/vue-router.esm-bundler.js'在本地复现故障
我的 uniapp 项目是基于 unibest 模板开发的，重新安装依赖后，在本地也能稳定复现出该故障：
[plugin:vite:import-analysis] Cannot find module 'vue-router\dist\vue-router.esm-bundler.js'可以确定是 @dcloudio/uni-h5@3.0.0-4070520250711001 依赖出现了问题，但是这个依赖我之前用了很久了，都没有问题，为什么就今天（2025-10-15）出问题了呢？
定位问题
明确依赖链
运行命令来查询依赖信息：
pnpm v @dcloudio/uni-h5@3.0.0-4070520250711001首先我全局查询依赖 @dcloudio/uni-h5@3.0.0-4070520250711001 ，确定该依赖使用了 vue-router@4.3.0 ，并且锁定主版本，允许安装次级版本。
但是在我刚刚重新安装的依赖内，是安装了 vue-router@4.6.0 版本。做出猜测： 会不会是 vue-router@4.6.0 版本导致了故障呢？
确定依赖发布时间
继续运行命令查询依赖信息：
pnpm v vue-router如下图所示，vue-router@4.6.0 版本是最近 20 小时发布的，所以就验证了为什么之前没出错，而今天却莫名其妙的出错了。所以可以锁定就是 vue-router@4.6.0 出现的故障。
阅读 vue-router@4.6.0 版本的更新日志
阅读此更新日志，得知 vue-router 在 4.6.0 版本做了重构，而且有可能会出现类型错误和文件未导出的问题。
仔细阅读本地安装的依赖，确实发现没有我所期望的文件：
所以破案了，是 vue-router@4.6.0 用了 tsup 做代码重构，所以导致构建产物名称变化，进而导致缺少文件的错误。
正式修复故障
预期会在 vue-router@4.6.1 内得到修复。
临时修复故障
如果很着急，需要实现版本回退，可以临时地用 pnpm.overrides 做依赖版本覆盖。在 package.json 内这样写：
{
"pnpm": {
"overrides": {
"vue-router": "4.5.1"
}
}
}不过 vue-router@4.6.1 已经发版更新，所以该临时写法可以暂时不用了。
作为破坏性变更，准备向未来迁移
经过沟通得知，vue-router/dist/vue-router.esm-bundler.js 已经属于弃用的配置了，未来就不会提供了。参考资料如下：
- 未来不提供
vue-router.esm-bundler.js的导出方式了： https://github.com/vuejs/router/issues/2569#issuecomment-3405172967 build: add deprecated vue-router.esm-bundler export： https://github.com/vuejs/router/commit/9b22edcff3acd9782dd86257b2744c1ae35a455e
已发布相关的报障 issue
贡献者
ruan-cat