npm-deps-cleanup

npm 依赖清理

减少 JavaScript 依赖体量。除非有具体理由需要更改，否则保留现有包管理器、锁文件、工作区布局和依赖范围风格。

工作流

1. 建立基线。
2. 移除未使用的直接依赖。
3. 在 monorepo 中统一直接依赖的版本。
4. 按传递依赖锁文件闭包对直接依赖排序。
5. 利用闭包数据找出低风险的次要版本／补丁版本升级。
6. 利用闭包数据找出值得内联的简单依赖。
7. 检查 e18e 建议的替换／移除项。
8. 重新安装、验证并报告实测影响。

包管理器检测

使用仓库现有的包管理器。优先查看明确的包元数据，而非锁文件：

1. 根目录 package.json 中的 packageManager。
2. 根目录 package.json 中的 devEngines.packageManager.name。
3. 根据锁文件推断。

如果存在 devEngines.packageManager，则使用其 name 检测 npm、pnpm、Yarn 或 Bun。将其 version 和 onFail 字段视为策略信号，而非更换包管理器的许可。

只有在包元数据无法确定包管理器时，才根据锁文件推断：

信号	包管理器
package-lock.json 或 npm-shrinkwrap.json	npm
pnpm-lock.yaml	pnpm
yarn.lock	Yarn
bun.lock 或 bun.lockb	Bun

使用对应的命令系列：

操作	npm	pnpm	Yarn	Bun
安装／更新锁文件	npm install	pnpm install	yarn install	bun install
移除直接依赖	npm uninstall <pkg>	pnpm remove <pkg>	yarn remove <pkg>	bun remove <pkg>
添加／更新直接依赖	npm install <pkg>@<version>	pnpm add <pkg>@<version>	yarn add <pkg>@<version>	bun add <pkg>@<version>
说明依赖	npm explain <pkg>	pnpm why <pkg>	yarn why <pkg>	bun pm why <pkg> if available
去重锁文件	npm dedupe	pnpm dedupe	yarn dedupe if available	reinstall and inspect
一次性工具	npx <tool>	pnpm dlx <tool>	yarn dlx <tool> if available	bunx <tool>

安全规则

• 分批进行，确保锁文件差异易于审查。
• 切勿盲目信任未使用依赖检测工具；应核查导入、配置文件、脚本、生成代码钩子、框架惯例、插件名称、CLI 和动态导入。
• 可以编写脚本和解析逻辑，以核实 package.json 和锁文件中的依赖记录。
• 将 peerDependencies、optionalDependencies、包的 bin 用法、测试夹具和已发布包的清单视为高风险项。
• 除非已证明替代方案等效，否则不要移除或内联用于安全、解析、加密、Unicode、URL 处理、日期／时间、i18n 或平台兼容性的依赖。
• 清理过程中不要更换包管理器、删除锁文件或重写工作区结构。
• 将包管理器的去重命令视为可能改变行为的操作。这些命令可能会在允许的范围内更改所选的传递依赖版本，因此保留结果前应检查锁文件差异并运行有针对性的验证。
• 测量前后变化：直接依赖数量、锁文件行数或条目数、包数量，以及可获取时估算的 node_modules 大小。

步骤 1：基线

收集以下信息：

• 所有 package.json 文件和工作区边界。
• 当前包管理器和锁文件。
• 按清单分区列出的直接依赖名称：dependencies、devDependencies、peerDependencies、optionalDependencies。
• 脚本、CI 或仓库文档中现有的验证命令。

编辑前记录基线指标：

git status --short
wc -l <lockfile>

如果已安装 node_modules，还应使用适用于当前平台的文件系统工具估算已安装内容的占用空间。不要让空间清理依赖于是否存在 node_modules；锁文件缩减才是主要指标。

步骤 2：移除未使用的直接依赖

静态分析器只能作为起点，不能作为依据。合适的工具包括 knip、depcheck，或已配置的仓库原生工具。如果尚未安装这些工具，可通过检测到的包管理器的一次性执行器运行。

对每个候选项：

1. 在代码、配置、包脚本、构建工具、测试和文档中搜索包名及已知导入路径。
2. 检查该依赖是否为已发布包清单、peer 契约、插件加载器、CLI 命令或动态 require/import 所必需。
3. 只有在确认不再有实际用法后才移除。
4. 使用检测到的包管理器重新安装，并运行有针对性的验证。

如果依赖只用于脚本或配置，可考虑在 dependencies 和 devDependencies 之间调整，而不是移除。

步骤 3：统一 Monorepo 中的直接依赖版本

在 Monorepo 中，检查多个包清单是否以不同版本／范围声明了相同的直接依赖。优先遵循现有策略：精确固定版本、caret 范围、catalog/protocol 用法、工作区协议或集中约束。

推荐做法：

• 使用 syncpack list-mismatches 或同类、不绑定包管理器的工具来查找差异。
• 如果各包可以共用同一个兼容版本，则统一直接依赖范围。
• 优先在清单层面保持一致，再考虑添加 overrides/resolutions。
• 仅将 overrides/resolutions 用于统一传递依赖版本或修复安全问题，并说明原因。

完成去重后，重新安装并检查清单和锁文件的差异。

然后考虑使用包管理器原生的锁文件去重命令：在可用时使用 npm dedupe、pnpm dedupe 或 yarn dedupe。Bun 没有直接对应的命令；运行 bun install 并检查锁文件是否收敛。谨慎使用这些命令，因为它们可能改变传递依赖的解析结果，即使未编辑清单也可能引入问题。

第 4 步：评估传递依赖锁文件闭包

针对每个重要的直接依赖，估算其闭包：从该直接依赖可到达的传递依赖锁文件条目集合。

报告以下两项：

• 总闭包：可从该依赖到达的所有包。
• 独占闭包：移除此依赖后会消失、且不会由其他直接依赖保留的包。

优先采用确定性的测量，而非猜测。与包管理器无关的备用方法：

1. 保存基线锁文件指标。
2. 暂时从所属清单文件中移除一个直接依赖。
3. 运行检测到的包管理器安装命令。
4. 测量锁文件行数／条目数减少量和包数量减少量。
5. 在测量下一个依赖前，恢复刚才的临时移除操作。

使用 npm explain、pnpm why、yarn why 或可用的包管理器依赖图命令，了解大型传递依赖存在的原因。根据影响和风险对依赖进行排序，而不只看原始大小。

第 5 步：寻找风险低、影响大的升级

利用闭包排名，针对升级到较新的次要版本或补丁版本后能减少传递依赖的直接依赖。

针对每个候选项：

1. 使用包管理器的过时／信息查询命令，检查可用的非主版本。
2. 查看变更日志／发布说明中的依赖树变动和兼容性说明。
3. 每次只升级一个依赖或紧密相关的一组依赖。
4. 重新安装，并比较升级前后的闭包指标。
5. 运行有针对性的测试及相关构建／类型检查命令。

除非用户明确接受迁移风险，否则避免升级主版本。

第 6 步：内联简单用法

利用闭包排名，找出代码库中的用法简单明了、但传递依赖成本较高的直接依赖。

仅在以下条件全部满足时进行内联：

• 用法很少，且易于完整梳理。
• 等效代码比保留该依赖更短或更清晰。
• 行为已由测试覆盖，或可通过少量特性测试覆盖。
• 该依赖并非用于处理跨平台、安全、解析、Unicode、区域设置或规范兼容性边缘情况。

所需行为简单时，优先使用原生 API，而不是新增替代依赖。

第 7 步：应用 e18e 指引

查阅 e18e，寻找其他可移除和可替换的候选项：

<runner> @e18e/cli analyze
<runner> @e18e/cli migrate --dry-run

将 <runner> 替换为检测到的单次执行器：npx、pnpm dlx、yarn dlx 或 bunx。

另请查看 e18e 模块替换列表：https://e18e.dev/docs/replacements/，了解已知替代方案。将建议视为候选项，而非强制要求；请验证打包／运行时行为并运行测试。

报告

总结结果并提供测量到的影响：

• 已移除或迁移的直接依赖。
• 已去重的直接依赖版本。
• 锁文件行数／条目数减少量。
• 可获得时，估算包数量或 node_modules 的减少量。
• 延后处理的高影响候选项及原因。
• 已运行的验证命令及结果。

若移除操作依赖静态分析而非运行时覆盖，请明确指出风险。