拆掉一个 8 年没更新的依赖:@vue/cli-plugin-unit-mocha 移除实录
结论先行:老项目里躺着的死依赖,不只会拖慢安装,还会在某个意想不到的时刻卡住 CI。判断一个依赖能不能删,别靠感觉,用三个可验证的判据:脚本有没有引用、版本对不对得上、依赖本身还活不活跃。
一、起因:一条不该存在的依赖链
CI 构建被一个包的 install 脚本卡住了(排查过程见前面那篇 unsafe-perm 的文章)。修好之后我没急着收工,而是顺着依赖树往上查了一层:
npm ls nodent-runtime
输出:
my-app@8.3.4
└─┬ @vue/cli-plugin-unit-mocha@3.12.1
└─┬ mocha-webpack@2.0.0-beta.0
└── nodent-runtime@3.2.1
链路清楚:@vue/cli-plugin-unit-mocha 直接依赖 mocha-webpack,后者又依赖了 nodent-runtime。
而 nodent-runtime 最后发布是 2018 年,版本线只有 3.0.0 到 3.2.1 六个版本,之后再没动过。
问题来了:这个插件到底还在用吗?
二、判据一:脚本里有没有引用
这是最快、也最有说服力的一条。打开 package.json 看 scripts:
{
"scripts": {
"serve": "vue-cli-service serve",
"build:dev": "vue-cli-service build --mode development",
"build": "vue-cli-service build --mode production",
"lint": "vue-cli-service lint --no-fix"
}
}
没有 test:unit。
@vue/cli-plugin-unit-mocha 这个包的唯一作用是给 vue-cli-service 注册一个 test:unit 命令。既然脚本里从来没调用过它,那它就永远没被触发过。
更进一步,再看代码目录:
ls test/ 2>/dev/null || echo "没有 test 目录"
连测试目录都没有。
这一条基本就能定性了:装了,但从来没用过。
三、判据二:版本对不对得上
再看版本号。插件是 @vue/cli-plugin-unit-mocha@3.12.1,而主体是 @vue/cli-service@4.5.19。
大版本差了整整一个。
Vue CLI 的插件生态有个硬性约束:插件的 major 版本必须和 @vue/cli-service 的 major 对齐。3.x 的插件挂在 4.x 的 service 上,就算你配了 test:unit 也跑不起来——它依赖的 @vue/cli-shared-utils@^3.12.1 和 service 4 用的 ^4.x 是两套互不兼容的 API。
所以这个插件从项目升级 Vue CLI 4 的那天起,就已经是死代码了。只是没人注意。
顺带一提,我查了它的依赖清单:
{
"dependencies": {
"jsdom": "^13.2.0",
"mocha": "^5.2.0",
"jsdom-global": "^3.0.2",
"mocha-webpack": "^2.0.0-beta.0",
"@vue/cli-shared-utils": "^3.12.1"
}
}
jsdom@13 是 2019 年的版本,mocha@5 是 2018 年的。一整套上古工具栈。
四、判据三:依赖本身还活着吗
| 包 | 最后发布 | 状态 |
|---|---|---|
nodent-runtime |
2018 年 | 8 年未更新,ES7 async 的 polyfill 运行时 |
mocha-webpack@2.0.0-beta.0 |
2018 年 | 一直是 beta,从未转正 |
jsdom@13 |
2019 年 | 已被 jsdom@20+ 取代多轮 |
mocha@5 |
2018 年 | 已被 mocha@10+ 取代 |
全是"考古级"的包。这类依赖的特征很明显:不报错,但会拖慢安装、扩大攻击面、偶尔在某个环节给你来个惊喜。
五、动手前的风险评估
删依赖是有风险的动作,删之前得想清楚会丢掉什么。
对 @vue/cli-plugin-unit-mocha 来说:
| 影响面 | 实际情况 |
|---|---|
vue-cli-service test:unit 命令 |
会消失,但项目从来没调用过 |
| 单测能力 | 项目本来就没有单测 |
| 构建流程 | 无关,这个插件不参与 build |
@vue/test-utils、chai 等 |
它们是独立的 devDependencies,不会跟着被删 |
最后一条要特别注意:@vue/test-utils 和 chai 在 package.json 里是独立条目,删掉插件不会自动带走它们。如果要连单测相关的一整套都清掉,得手动再删这两个——但它们本身没有传递依赖问题,留着也不影响。
结论:可以安全移除。
六、操作步骤
# 1. 备份,防止手滑
copy package.json package.json.bak
# 2. 卸载(用 npm uninstall,别手动改 package.json)
npm uninstall @vue/cli-plugin-unit-mocha
# 3. 彻底重来,避免 lock 里的残留
rmdir /s /q node_modules
del package-lock.json
npm install
为什么用 npm uninstall 而不是手动编辑 package.json?
手动删掉一行,package-lock.json 里那棵子树还在。npm 下次 install 时可能会因为 lock 文件里的记录又把包装回来,或者留下一个"package.json 里没有、但 node_modules 里有"的幽灵依赖。
npm uninstall 会同时更新 package.json 和 lock 文件,是唯一可靠的方式。
为什么要删 lock 重装?
这一步是为了彻底清掉 lock 里的历史记录。虽然 npm uninstall 通常会正确处理,但老项目里 lock 文件被多次手工改过的概率很高(尤其是用过 yarn 和 npm 混装的),删掉重建最干净。
七、最容易踩的坑:lock 文件必须同步提交
这一步如果漏了,会引出跟原问题看起来毫无关系的新报错。
CI 上的安装命令有两种:
| 命令 | 行为 |
|---|---|
npm install |
lock 与 package.json 不一致时,自动更新 lock 并继续 |
npm ci |
lock 与 package.json 不一致就立即失败,一个包都不装 |
npm ci 的报错长得像这样:
npm ERR! `npm ci` can only install packages when your package.json
and package-lock.json are in sync. Please update your lock file
with `npm install` before continuing.
这跟依赖冲突、Node 版本、权限问题全都无关,纯粹是文件不同步。
所以规矩很简单:package.json 和 package-lock.json 必须一起提交,一个都不能少。
顺便验证一下删除效果:
npm ls nodent-runtime
# 应该输出 (empty)
八、顺带发现的一个配置问题
清理依赖时还注意到 package.json 里有这么一段:
"resolutions": {
"**/core-js-compat": "3.39.0",
"**/minimatch": "3.1.2"
}
resolutions 是 yarn 1.x 的字段,npm 完全不认。
如果这个项目实际用 npm 装包(从 CI 日志看是的),那这几行一直在空转——它想强制统一的版本,一次都没生效过。
npm 的对应能力是 overrides,需要 npm 8.3+:
"overrides": {
"core-js-compat": "3.39.0",
"minimatch": "3.1.2"
}
不过这里有个决策要做:是改成 overrides 让它真正生效,还是干脆删掉?
我的建议是先别急着改。空转了这么多年的版本约束,一旦真正生效,依赖树会发生变化,可能引入新的不兼容。要改就单独拉一次提交、单独验证,别和"删死依赖"混在一起。
一次只改一件事,这是排查成本最低的做法。
九、清理死依赖的通用流程
把这次的经验抽象一下,五个步骤:
1. 定位
npm ls <包名> # 看是谁带进来的
2. 验证是否被使用
- scripts 里有没有对应命令
- 源码里有没有 require / import
- 配置文件(vue.config.js、babel.config.js)里有没有引用
3. 看版本是否还对得上
大版本错配往往意味着"升级主体时忘了它"。
4. 评估移除影响
列清楚会丢什么能力,确认不影响构建和运行。
5. 删除 + 清 lock + 重装 + 提交两个文件
十、小结
- 判断依赖能不能删,别靠直觉,靠判据。脚本没引用、版本对不上、上游停止维护,三条里占两条就可以动手。
npm uninstall比手动改package.json可靠,因为它同时处理 lock。package.json和package-lock.json必须成对提交,否则npm ci会以一种完全不相干的报错形式失败。resolutions是 yarn 的字段,npm 下是死配置。但要改就单独改,别和依赖清理混在一次提交里。
最后说个感受:老项目的依赖树就像地质层,每一层都记录着某次升级的痕迹。@vue/cli-plugin-unit-mocha@3.12.1 这一层,记录的是"当年从 Vue CLI 3 升级到 4 时,有个单测插件被落下了"。
它安静地躺了几年,直到某个 CI 环境换了权限模型,才突然冒出来咬人一口。
posted on 2026-11-10 19:58 fox_charon 阅读(10) 评论(0) 收藏 举报
浙公网安备 33010602011771号