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 文件吗，直接改字段名不就行了？没错，手动改当然可以，但