npm 依赖管理实战：分清 dependencies 与 devDependencies，安全清理无用依赖

1. 依赖分类这件事，为什么值得认真对待

几乎每个用 Node.js 写过项目的人都见过这样的 package.json：dependencies 里躺着 ESLint、Prettier、Jest，devDependencies 里却放着 axios、lodash，甚至有的包两边各出现一次。刚开始写项目的时候，“能跑就行”是大多数人的心态，反正 npm install 一把梭，装进去什么都能用，谁有空去管它是生产依赖还是开发依赖。

但当你开始接手别人的项目，或者自己的项目跑了一两年之后，这种混乱会以各种方式反咬你一口。最直接的一口，就是部署体积和安装时间。现在很多项目都走 Docker 部署，镜像里要执行 npm install --production，如果构建工具、代码检查工具全躺在 dependencies 里，生产镜像会白白多出一堆 node_modules 文件。你可能觉得几百 MB 无所谓，等带宽吃紧、磁盘告急的时候就不会这么想了。另一个隐性问题与安全相关：报告显示 npm 生态里相当一部分已知漏洞来自开发依赖，如果把开发依赖全部发布到生产环境，攻击面就平白大了一圈。

所以“正确归类包”和“删除无用开发依赖包”这两件事，表面上是 package.json 里的字段挪动，本质上是在给项目的依赖矩阵做一次健康体检。我从几个真实项目里踩过不少坑之后，总结了一套自己一直在用的归类原则和清理流程，这篇就完整分享出来。

1.1 一个混乱的 package.json 会带来什么后果

先看一个我实际遇到过的案例。当时接手一个内部中后台前端项目，package.json 长这样：

json复制{
  "dependencies": {
    "@babel/core": "^7.18.0",
    "@babel/preset-env": "^7.18.0",
    "axios": "^1.3.0",
    "eslint": "^8.20.0",
    "webpack": "^5.70.0"
  },
  "devDependencies": {
    "vue": "^3.2.30",
    "vue-router": "^4.0.13"
  }
}

注意这里的问题：Vue 和 Vue Router 是运行时依赖，却被放进了 devDependencies；Babel、ESLint、Webpack 是开发构建工具，反而放在了 dependencies。理论上，只要开发者本地执行 npm install，两者都会被安装，开发时该跑的都能跑。但一部署就出事了：部署脚本执行 npm install --production 时，Vue 根本不会被装上，页面直接白屏；而生产服务器上却多出了 ESLint、Webpack 这一堆根本用不到的垃圾包。

这个案例本身就是最好的理由：归类正确与否，开发时没有体感，部署和交付时才现原形。

另一个容易被忽视的影响是协作成本。你的同事 clone 完代码，看到 devDependencies 里躺着 axios，大概率会疑惑“这项目是把 axios 当开发工具用的吗？”他可能不敢乱动，也可能“好心”帮你把它挪到 dependencies，来回几次之后，依赖清单的维护彻底失去约束力。项目的依赖结构是会说话的，写乱了，就是在给后来人埋障碍。

1.2 分类的核心原则：一句话总结

每次有朋友问我怎么给依赖归类，我都只给一句话：项目线上运行的时候必须 require/import 的包，放进 dependencies；只在开发、测试、构建阶段用的工具，放进 devDependencies。

这句话听起来简单，实操起来还有几个边界情况要额外注意，比如代码中用到的工具函数、UI 组件库、请求库、状态管理库，都属于运行时依赖。而 Babel、Webpack、Vite、ESLint、Prettier、TypeScript（在某些项目里）、Jest、Vitest、各种 loader 和 plugin，都是开发依赖。

TypeScript 要单独拿出来说。如果是纯业务项目，TypeScript 编译完之后产物是 JS，运行时不再需要 tsc，所以 TypeScript 通常放在 devDependencies。但如果你的项目本身是一个给其他开发者用的库或 CLI 工具，而且对外导出了 .d.ts 类型声明，TypeScript 的某些能力在编译用户代码时会被用到，这时候 TypeScript 可能需要放进 dependencies，或者以 peerDependencies 的方式处理。这个要具体情况具体分析，没有一刀切的答案。

确定这个原则之后，后面所有操作都有了判断依据，不需要在“这个包该放哪”的问题上反复纠结。

2. 正确归类包的实际操作方法

观念理顺了，接下来就是实际操作。这一步很多人会想：package.json 不就是个 JSON 文件吗，直接改字段名不就行了？没错，手动改当然可以，但这不是最优解。直接拿编辑器改容易引发两个问题：一是手滑拼错包名，二是没有同步更新 package-lock.json，导致锁文件里记录的依赖树与实际 package.json 不一致，后面执行 npm install 时会莫名其妙多出很多 diff。

所以我更推荐用 npm 自带的命令来调整归类，它们是专门为这个场景设计的，会自动同步锁文件，不会留给后面的人一堆历史遗留冲突。

2.1 安装时用对命令：一次性做到位

给新项目装依赖时，养成用 --save 和 --save-dev 区分的好习惯，能省去后面所有手工调整的麻烦。

• 运行时依赖，比如 axios、vue、react、lodash、dayjs：

bash复制npm install axios
npm install vue-router --save

• 开发依赖，比如 eslint、prettier、jest、vite、webpack：

bash复制npm install eslint --save-dev
npm install --save-dev @babel/core

注意 --save-dev 可以简写成 -D，--save 也可以省略不写，因为 npm 5 之后默认就会把包写入 dependencies。省略写法的坑就在这：你少敲几个字符，包却默认进了生产依赖，后续还得专门挪出来。

这里插一句 yarn 和 pnpm 的情况。Yarn Classic 里对应的是 yarn add <pkg> 和 yarn add -D <pkg>；pnpm 对应的是 pnpm add <pkg> 和 pnpm add -D <pkg>。逻辑都是同一个，只是命令关键词不同，实际用哪个包管理器，就按哪个的语法来。

2.2 处理已归错位置的包：如何把它们挪到正确阵营

如果你已经有一个跑了一段时间的项目，依赖归类是乱的，这时候不需要卸载重装，只需要分两步做“乾坤大挪移”。

比如现在 axios 在 devDependencies 里，需要挪到 dependencies。第一步，把它作为运行时依赖重新安装一次：

bash复制npm install axios --save

这条命令的执行效果是：npm 会检查 axios 是否已经存在于依赖树中，如果存在就会更新它在 package.json 中的归属字段；如果不存在就正常安装。第二步，检查 node_modules 和锁文件是否一致。重新执行：

bash复制npm install

这样 npm 会基于更新后的 package.json 重新整理依赖树，如果 devDependencies 里已经自动移除了 axios 的记录，说明归类已经完成。但有时候 npm 会因为你没有显式卸载而保留旧的记录，这时候需要手动把 devDependencies 里的 axios 删掉，再执行一次 npm install 来同步锁文件。

其实这里有个更省事的做法：直接手动编辑 package.json，把包从 devDependencies 挪到 dependencies，然后删掉 node_modules 和 package-lock.json，执行 npm install 重新生成。这个方案看起来粗暴，但效果很干净。缺点（也需要注意）是锁文件会整体重算，可能产生大量无关 diff，对多人协作的项目不友好。所以我的建议是：如果项目只有你在维护，怎么折腾都行；如果是一个多人协作的项目，一定要用 npm 命令自动同步锁文件，最小化变更范围。

2.3 面对“边界型依赖”：这些包最容易被分错

说明一下，实际操作中会遇到一批很难一眼判断归类的“边界型依赖”，这里单独列出来讲。

第一类是 Ant Design、Element Plus 这类组件库。它们运行时必须加载，用于渲染页面组件，所以应该放 dependencies。很多初学者会误以为“组件库不就是开发时写代码用的吗”，随手就给装进了 devDependencies，结果上线后样式全丢或组件直接报错。

第二类是 lodash 这类工具函数库。只要代码运行时还在调用其方法，就必须放 dependencies。这个原则很清晰：只要你 import 的代码不是被构建流程读取的，它就要跟随你的产物上线。

第三类是 dotenv。dotenv 通常在应用启动时就被加载了，它负责读 .env 文件里的环境变量，运行时是需要的，所以放 dependencies。但是，如果你只在配置构建脚本时用了 dotenv，比如用 Node 脚本读取构建时的环境变量，那它可以放 devDependencies。这个真的要看你的使用场景。实际项目中我见过太多直接把 dotenv 放 devDependencies 然后生产环境启动时找不到模块的案例。

第四类是 cross-env。它是个极好的例子，因为它几乎只在 package.json 的 scripts 里出现，用来自动识别 Windows 的跨平台环境变量设置，应用运行时是通过 start 脚本间接依赖它的。严格来说，start 脚本执行的命令里如果用了 cross-env NODE_ENV=production，而你的部署流程会执行 npm start，那 cross-env 应该放 dependencies。如果你的部署流程只执行 node app.js，cross-env 只是本地开发 scripts 使用，那它就可以放 devDependencies。结论就是：不要看包名判断，看你的 npm scripts 被谁执行。

第五类是各种 Babel 插件、Webpack 插件、Vite 插件。它们的功能是处理代码而不是被业务代码调用，绝大多数放 devDependencies。

3. 删除无用依赖包的排查与清理全流程

归类清完之后，下一个更常见也更难缠的问题是“删除无用的开发依赖包”。难就难在，你怎么知道一个包有没有被用过？靠眼睛看代码是看不过来的，靠猜早晚要出错。

我自己刚工作那会儿吃过一次大亏：看到项目里装了 moment，全局搜了下代码发现没有 import，以为是无用依赖，直接卸载了。结果某天一个没搜到的配置里偷偷用了 moment 做日期格式化，生产环境直接报错。从那以后我就明白，清理依赖之前一定要做好“证据收集”，用工具代替肉眼搜索。

3.1 摸底：先让工具帮你列出嫌疑名单

目前社区里比较常用、我实测也比较稳的工具是 depcheck。它的原理是解析项目中的所有文件，找出代码里出现过的 import、require 语句，再和 package.json 里声明的依赖做对比，最后输出三类信息：

• 未使用的依赖：package.json 里声明了，但代码中找不到引用
• 未使用的开发依赖：devDependencies 里声明了，但代码中找不到引用
• 使用了但未声明的依赖：代码中有引用，但 package.json 里没有声明

安装 depcheck 可以不用装在项目里，直接全局装或者用 npx 跑：

bash复制npx depcheck

执行完成后它会输出一个清单，类似：

bash复制Unused dependencies
* moment
* lodash

Unused devDependencies
* eslint-plugin-import
* prettier

Missing dependencies
* dayjs

光看这个输出还不够，depcheck 只能作为“嫌疑名单”，不能直接当“判决书”。很多包属于“配置型工具”，比如 ESLint 插件、Babel 插件、PostCSS 插件，它们不会出现在业务代码的 import/require 里，而是被对应工具的配置文件加载。depcheck 虽然对常见配置有一定识别能力，但毕竟覆盖不全。所以它的正确用法是：帮你缩小排查范围，而不是帮你一次性做决定。

3.2 二次确认：逐个验证再动手删

拿到嫌疑名单后，第二步是逐个确认。我的操作习惯是分三类来验证：

第一类是纯工具链插件。比如 eslint-plugin-vue、@babel/preset-env 这类，它们一定出现在 .eslintrc.js、babel.config.js、vite.config.js 或类似配置文件里。验证方法很简单：查看对应对应工具的配置文件里有没有对应的引用，确认之后可以直接判断为“有用”，哪怕 depcheck 报它未使用也不需要删。

第二类是曾经用过但现在确认不用的包。比如项目从 Moment.js 迁移到了 Day.js，那 moment 通常是真没用了。但为了保险，我在删除前会再执行一次：

bash复制grep -r "from 'moment'" src/ 2>/dev/null

如果搜索结果为空，再结合 depcheck 的输出，基本可以放心删。搜索范围要注意别漏掉非 src 目录，尤其是 scripts 目录、配置目录、测试目录，我踩过的坑就是只搜了 src，结果在 jest.setup.js 里引用了却没搜到。

第三类是最容易忽略的“隐式依赖”。比如项目根目录可能藏着 postcss.config.js，里面直接 require('autoprefixer')，但 autoprefixer 是通过 PostCSS 的插件机制加载的，未必会被 depcheck 扫到。这种隐式引用的验证方法是全局搜 require 关键字再加包名。有一个额外的检查技巧：卸载一个包之后，不要只跑一次构建就结束，要跑一遍完整的测试集、构建脚本、以及项目主要的启动命令，全方位确认没有遗漏引用。

确认好之后，再执行删除命令：

bash复制npm uninstall moment
npm uninstall --save-dev eslint-plugin-import

pnpm 用户对应的命令是 pnpm remove moment，yarn 用户是 yarn remove moment。安装时我见过很多人纠结该用 npm 还是 yarn，但卸载时反而没人在意了，这个意识需要补上：卸载和安装是用同一个包管理器的，锁定哪个就全程用哪个，混用会导致锁文件状态异常。

3.3 手工排查的兜底方案：搜索脚本和约定清单

如果你不想引入 depcheck，或者项目里的包数量不多，也可以纯手工排查。我提供一个自己一直沿用的三段式方法。

第一段，把 node_modules 目录排除，全局搜索“没有任何代码引用的包名”。使用 VS Code 的话，在搜索面板里输入包名就可以，它会列出所有引用位置，但要记得排除 node_modules 和构建产物目录。

第二段，把 scripts 目录、配置文件目录、测试目录全部纳入搜索范围。很多包只在测试环境用，只在构建环境用，只在发版脚本里用，这些用一次也不能删。

第三段，先搜包名，再搜它的常见导入别名。因为有些包导入时会被改名，比如 import moment from 'moment'，代码里搜“moment”能搜到，没问题。但如果有人写了 import dayjs from 'dayjs'，搜索“dayjs”就行。可有些人会用别名：import day from 'dayjs'，搜索“dayjs”就找不到了。所以排查别名是特别容易被漏掉的环节，要同时搜“包名”和“导入时的引用名”。但这属于最后一层保险，实际先跑一遍 depcheck 能省很多时间。

4. 实操过程中的常见问题与排查技巧实录

讲了这么多方法论，最后把我在实际清理过程中遇到过的典型问题和排查思路整理一下，很多都是真实项目里会碰到的。

4.1 清理完依赖后，本地启动直接报 module not found

这是最常见的情况。你明明在所有代码里都没搜到引用，卸载完一跑 npm run dev，系统提示找不到模块。基本原因有两种：

第一种是没搜到非业务目录的引用文件，比如 Babel 配置或者 Webpack 配置里引用了。解决办法是启动前全局搜一遍，核心点是不要把“构建配置”当作“业务代码”，构建配置里引用的包也是合理引用。

第二种是某个被卸载的包被另一个包间接依赖，卸载之后另一个包运行报错。这种属于传递依赖（传递依赖），需要确认之前是不是有代码“隐式依赖”了一个没在 package.json 里声明的包。错误提示通常会告诉你具体哪个模块找不到，这时根据模块名反查它是哪个包的子依赖，比较稳妥的做法是把这个模块对应的包重新显式安装到正确的依赖分类里。

4.2 清理完依赖后，生产构建产物体积并没有明显变小

很多人在清理依赖时抱有一个期待：删掉一堆包，产物肯定变小。结果发现构建出来的 JS 文件体积几乎没变。其实这很常见，原因并不难理解：构建工具（Vite、Webpack）默认只打包代码中实际 import 的模块，那些没有被引用的包根本不会进产物。清理无用开发依赖包的意义在于减少 node_modules 体积、加快 CI 安装速度、缩短镜像构建时间，而不是直接影响业务产物大小。

如果你想让业务产物变小，正确方向应该是去看当前有哪些运行时依赖被全局引入了但没有按需加载，比如整个组件库被全局注册但只用到了其中少数组件。这个逻辑要搞清楚，清理开发依赖代码的作用域在“工程依赖链条”而不是“产物代码”。

4.3 用 --production 安装时莫名报错，但本地开发又一切正常

如果你的部署流程是按生产依赖安装，报错内容经常是“Cannot find module 'xxx'”，大概率是某个运行时依赖被错放进了 devDependencies。这时对应检查方案是去代码里搜这个模块的 import/require。如果找到了，就应该把它挪到 dependencies，方法参考前面第二部分的 npm install --save 重新安装，然后跑一次测试构建验证。

这里有个调试技巧：本地模拟生产安装时，不要直接删 node_modules，可以这样操作：

bash复制npm prune --omit=dev

它的作用是移除当前 node_modules 中 devDependencies 里的所有包，保留 dependencies 的包。执行完之后你可以启动生产模式，看是否报错。如果报错，说明缺少的包确实是生产依赖。排查完要恢复开发环境，再执行一次：

bash复制npm install

下面是一个小型速查表，我在排查问题时经常参考：

4.4 别忽略幽灵依赖这个隐蔽问题

清理无用依赖时还有一个更容易被忽视的现象叫“幽灵依赖”，也常被翻译为“幻影依赖”。它的表现是：某个包并没有被直接写进你的 package.json，但你代码里却能正常引到它。原因是它是某个其他依赖的子依赖，npm 3 之后把依赖树拍平了，所有子依赖都提升到顶层 node_modules，于是你不需要在 package.json 里声明就能直接引用。

这种代码是“行走的定时炸弹”。某个版本下，这个子依赖可能还存在，升一次级或者某个主依赖变更之后，它就被移出了顶层，你的代码瞬间全线报错。清理无用依赖时很容易踩到这个坑，因为你卸载了一个看起来无用的包，实际却把这个“幽灵依赖”的源头给切断了。比如项目 A 依赖了 webpack，而 webpack 塞了一层 schema-utils 在顶层，你的代码直接用了 schema-utils 做校验。某天你决定不用 webpack 了，卸载了 webpack，schema-utils 也随之消失，其他代码段因为没有显式声明就直接崩了。

如果你用的是 pnpm，幽灵依赖基本能被结构性禁用掉，npm 项目需要借助 eslint-plugin-import 的 no-extraneous-dependencies 规则来检查代码中是否引用了 package.json 里未声明的包。这个规则配置好之后，CI 阶段就能直接拦截这类问题。

5. 一套可持续的依赖健康维护方案

清理依赖不是一次性手术，做完就完了。如果平时不建立约束机制，过几个月包管理器又会把一堆东西堆回来。我在团队里推行了一套比较轻量的维护办法，不增加太多额外工作量，效果却很好。

5.1 给团队立几条简单规矩

第一条规矩：安装任何包之前，先问一句“它会被业务代码 import 吗？”。被 import 的放 dependencies，只是被工具链加载的就放 devDependencies。

第二条规矩：删除任何包之前，先在仓库里全局搜索引用，并且把测试目录和配置文件目录加进搜索范围。

第三条规矩：不要手动改 package.json 里的版本号，通过 npm install <pkg>@<version> 来升级，避免 package-lock.json 里的依赖树和声明文件脱节。

第四点属于加分项，可以在 code review 时留意新加的依赖属于哪个分类。如果提交记录里出现把构建工具装进 dependencies 的情况，顺手提一句，比事后清理省事得多。

这些规矩不需要做成文档写进 wiki，我认为在项目 README 的“开发指南”一节里加几行说明就够了，很多团队的问题不是缺乏规章制度，而是缺乏随手维护的意识。

5.2 定时体检：让清理变成常规节奏

我自己的习惯是每个月或者每个迭代周期结束，跑一次依赖体检。步骤很简单：

• 第一步：执行 npm outdated，查看哪些依赖有可用更新
• 第二步：执行 npx depcheck，生成未使用依赖清单
• 第三步：逐个确认清单后统一清理
• 第四步：执行 npm audit，查看安全漏洞情况

这个流程跑下来通常只要十几分钟。但如果项目已经很久没清理过，第一次跑会用更久。磨刀不误砍柴工，几次之后项目依赖就能维持在一个很清爽的状态。

这里想特别说明的一点是：不要为了追求“零未使用开发依赖”而把还在正常工作的插件强行删掉。“未使用”有时候只是工具识别的策略不够全面，比如有些 CLI 工具会在命令行中被调用，有些插件会在 IDE 配置里发挥作用却不出现在业务代码里，这类不加甄别直接删除反而容易翻车。

5.3 用 lockfile 锁住当前成果

最后再提一件事：无论怎么清理和分类，lockfile 都是你最好的朋友。执行任何依赖变更之后，一定要确保 package-lock.json（或 pnpm-lock.yaml、yarn.lock）处于最新状态，并且把它提交到代码仓库。

很多人不重视 lockfile，其实它是“依赖可复现”的唯一保证。同一个 package.json 在不同时间点执行安装，可能装出不同版本甚至不同的传递依赖树。只有 lockfile 能把团队所有人的 node_modules 固定在一个状态，也把 CI 和生产的安装结果固定下来。清理完无用依赖后，建议执行一次完整安装并观察 lockfile 的变化，确认没有异常的依赖丢失或版本漂移再提交。

我在清理一些历史项目的依赖时，会先跑一遍测试套件记录结果，再清理，再跑一遍测试套件，两边结果一致才算结束。这个方法看起来笨，但对上线任务来说很管用。