别再搞混了!package.json中dependencies和devDependencies的5个实际应用场景
每次接手一个新项目,或者准备把代码部署上线时,你是不是也对着 package.json 里那一长串依赖项感到一丝困惑?哪些是运行时必需的,哪些只是开发工具?这个问题看似基础,却实实在在地影响着项目的构建、部署和团队协作。很多开发者凭感觉或习惯来划分依赖,结果往往导致本地运行一切正常,一到CI/CD流水线就构建失败,或者生产环境的包体积莫名臃肿。今天,我们不谈枯燥的定义,而是深入到五个真实且容易踩坑的场景里,帮你彻底厘清这两者的边界,让你的项目依赖管理既清晰又高效。
1. 环境隔离:从本地开发到CI/CD流水线
依赖管理的首要原则是环境隔离。dependencies 和 devDependencies 最直观的区别,就在于它们所服务的环境不同。但“环境”这个词太宽泛了,我们需要把它拆解到具体的操作环节中。
想象一下典型的开发流程:你在本地编写代码,会用到代码格式化工具(如Prettier)、测试框架(如Jest)、打包工具(如Webpack)。这些工具帮助你产出最终要运行的代码,但它们本身并不会出现在线上服务器。这就是 devDependencies 的典型成员。
而你的应用代码,比如一个Express服务器,它需要 express 这个包才能处理HTTP请求。无论在生产环境还是测试环境,这个能力都是必需的。因此,express 必须放在 dependencies 中。
为什么严格区分如此重要? 核心在于 npm install 命令的 --production 标志。当你在服务器或CI/CD环境中执行 npm install --production 时,NPM只会安装 dependencies 下列出的包,完全跳过 devDependencies。这带来了几个关键好处:
- 更快的部署速度:无需下载和安装庞大的开发工具链,显著缩短部署时间。
- 更小的生产镜像体积:Docker镜像、服务器目录会更精简,安全性也更高(减少了潜在的攻击面)。
- 避免环境冲突:有些开发工具(如特定版本的TypeScript编译器)可能与生产环境的Node版本不兼容,不安装它们就避免了这类问题。
一个常见的反例是把 webpack 放入了 dependencies。这会导致生产环境也安装了这个可能超过100MB的构建工具,但它除了占用空间外毫无用处。
提示:你可以通过
npm list --production快速查看在生产模式下会安装哪些包,这是一个很好的自查习惯。
2. 构建工具链:谁该为最终产物负责?
现代前端开发离不开复杂的构建工具链。Babel转译、TypeScript编译、SCSS预处理、代码打包和压缩……这些工具在开发阶段至关重要,但它们的工作在代码部署前就已经完成了。
关键判断标准是:这个包是否会被打包进最终的发布产物(bundle)中?
-
属于
devDependencies:所有处理源代码的工具。- 编译器/转译器:
@babel/core,typescript - 打包器:
webpack,vite,rollup - 代码处理器:
sass,postcss - 代码质量工具:
eslint,prettier这些工具就像工厂里的机床和模具,产品出厂后,机床本身并不会跟着产品一起发货。
- 编译器/转译器:
-
属于
dependencies:所有成为最终产物一部分的库。- 框架/库运行时:
react,vue,lodash - 样式库:
bootstrap,antd(虽然它们可能被构建工具处理,但其CSS/JS代码需要被引入最终bundle) - Polyfill:
core-js(如果通过import方式引入) 这些是构成产品本身的“原材料”或“零部件”。
- 框架/库运行时:
让我们看一个Vue项目的典型依赖划分示例:
{
"name": "my-vue-app",
"dependencies": {
"vue": "^3.3.0",
"vue-router": "^4.2.0",
"pinia": "^2.1.0",
"axios": "^1.5.0"
},
"devDependencies": {
"@vitejs/plugin-vue": "^4.4.0",
"typescript": "^5.2.0",
"vite": "^4.5.0",
"eslint": "^8.50.0",
"@types/node": "^20.8.0"
}
}
这里,vue 等是应用运行的核心,而 vite、typescript 只是构建阶段的助手。混淆它们,尤其是在配置Dockerfile时,会导致构建阶段缺失关键工具,或者运行阶段镜像臃肿。
3. 测试与质量保障:何时需要,何时不需要?
测试是保证代码质量的核心环节,但测试代码和测试框架本身的生命周期与业务代码截然不同。
-
测试框架与断言库:
jest,mocha,chai,@testing-library/react。这些是编写和运行测试的工具,它们只在开发或CI环境中使用,以验证dependencies中的业务代码是否正确。因此,它们毫无争议地属于devDependencies。 -
测试工具/模拟库:
sinon(用于创建spy、stub),nock(模拟HTTP请求),jsdom(在Node中模拟浏览器环境)。同理,它们也是开发阶段的辅助工具。 -
一个需要仔细斟酌的灰色地带:端到端(E2E)测试工具,如
cypress或puppeteer。它们的情况更复杂一些:- 如果你的E2E测试是开发流程的一部分(例如在
npm run test:e2e中运行),用于在合并代码前验证功能,那么它们应放在devDependencies。 - 但在某些监控或生产环境健康检查的场景下,可能会有专门的、独立于应用的服务来运行E2E测试。这种情况下,运行这些测试的服务需要将
cypress作为其自身的dependencies,但这已经属于另一个独立项目了。
- 如果你的E2E测试是开发流程的一部分(例如在
核心原则:测试是为了验证生产代码,而不是生产代码的一部分。 将测试相关依赖误放入 dependencies,是新手常犯的错误,这会让你的生产镜像平白无故多出几百MB的内容。
4. 微服务与Monorepo架构下的依赖隔离
在单体应用中,依赖划分相对简单。但当项目演进为微服务或采用Monorepo(如使用 pnpm workspaces, Lerna, Turborepo)管理多个包时,依赖管理就变成了一个需要精心设计的架构问题。
场景:共享工具包的依赖类型
假设你有一个Monorepo,包含一个共享的 @my-company/eslint-config 配置包,和一个业务应用包 app。
- 在
@my-company/eslint-config的package.json中,eslint及其插件是它运行所必需的(没有它们,这个配置包无法工作)。因此,eslint应该被列为这个工具包的dependencies。 - 在业务应用
app中,你通过npm install @my-company/eslint-config引入这个共享配置。此时,app只需要在开发时使用这个配置来检查代码,所以@my-company/eslint-config应该被列为app的devDependencies。
微服务间的公共库
如果多个微服务都使用一个内部的 @my-company/utils 工具库,这个工具库提供了通用的数据处理函数。那么在每个微服务的 package.json 中,@my-company/utils 都必须是 dependencies,因为服务在运行时需要调用这些函数。
下表对比了不同场景下共享包的依赖归属:
| 共享包类型 | 在共享包自身的 package.json 中 | 在消费该包的业务项目的 package.json 中 |
|---|---|---|
| 构建/代码质量工具 (如自定义Webpack插件、ESLint配置) | 其依赖的底层工具(如webpack、eslint)应列为 dependencies | 该共享工具包本身应列为 devDependencies |
| 公共业务工具库 (如工具函数、常量定义) | 其依赖的第三方库(如lodash)应列为 dependencies | 该工具库本身应列为 dependencies |
TypeScript类型定义包 (@types/xxx) | - | 几乎总是列为 devDependencies |
这种清晰的划分,确保了在构建单个服务或应用时,只会安装它真正需要的运行时依赖,保持了各服务的轻量化和独立性。
5. 类型定义、文档生成与“仅类型”依赖
JavaScript生态中还有一些特殊的包,它们的存在形式比较微妙,常常引发困惑。
TypeScript类型定义 (@types/*)
对于像 lodash 这样的纯JavaScript库,为了获得TypeScript的类型提示,我们需要安装 @types/lodash。这个包只包含 .d.ts 类型声明文件,在代码被编译成JavaScript后,它们就完成了使命。因此,绝大多数 @types/* 包都应该放在 devDependencies 中。唯一的例外是,当你发布一个库,并且这个库的类型定义是其公共API的一部分时,才需要将 @types 依赖放入 dependencies(或者更好的方式是使用TypeScript的 declaration: true 选项将类型直接打包进你的库)。
文档生成工具
jsdoc, vuepress, docusaurus 这类工具用于从代码注释生成静态文档网站。文档站点本身是一个独立的产物,通常有独立的构建和部署流程。因此,在你的源代码项目中,这些工具应该列为 devDependencies。你可能会有一个 docs 文件夹或一个独立的文档仓库,在那里运行 npm run docs:build。
“Peer Dependencies” 的邻居:那些你“只需要它存在”的包
这是一种更高级但真实存在的场景。假设你开发一个Webpack插件 my-webpack-plugin,这个插件需要用到 webpack 的某些API。你会把 webpack 放在哪里?
- 放在
dependencies?不行,这会强制安装特定版本的webpack,可能与使用你插件的主项目版本冲突。 - 放在
devDependencies?也不行,因为用户安装你的插件时,如果他们的环境没有webpack,插件根本无法运行。 - 正确答案是使用
peerDependencies。你通过peerDependencies声明:“我的插件需要webpack,但请使用项目本身的webpack版本”。同时,为了让你自己能开发和测试这个插件,你需要在本地的devDependencies里安装一个webpack实例。
// my-webpack-plugin 的 package.json
{
"name": "my-webpack-plugin",
"peerDependencies": {
"webpack": "^5.0.0"
},
"devDependencies": {
"webpack": "^5.80.0" // 用于本地开发和测试
}
}
理解这些特殊案例,能帮助你在更复杂的生态位中做出精准的依赖管理决策,避免给协作者带来不必要的版本冲突或环境问题。
依赖管理是项目工程化的基石。区分 dependencies 和 devDependencies 远不止是遵循规范,它直接关系到构建的确定性、部署的效率和团队协作的顺畅度。下次你执行 npm install 时,不妨多花几秒钟思考一下这个包的真实身份,这个微小的习惯,能为你后续的开发扫清很多障碍。
391



被折叠的 条评论
为什么被折叠?



