记一次因 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 导致的错误。

log 复制代码

[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 模板开发的，重新安装依赖后，在本地也能稳定复现出该故障：

log 复制代码

[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）出问题了呢？

定位问题

明确依赖链

运行命令来查询依赖信息：

bash 复制代码

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 版本导致了故障呢？

确定依赖发布时间

继续运行命令查询依赖信息：

bash 复制代码

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 内这样写：

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 的导出方式了： github.com/vuejs/route...
build: add deprecated vue-router.esm-bundler export： github.com/vuejs/route...

已发布相关的报障 issue

vue-router.esm-bundler.js not exported in vue-router@4.6.0 version