基于React的前端库包如何在package.json中划分三类依赖？

针对你用React构建组件库、并在主包按需引入的场景，下面明确package.json里三个依赖字段的划分逻辑、具体示例和通用规则：

核心划分原则 #

先搞清楚三个字段的本质：

• peerDependencies：声明你的库必须由宿主项目（也就是你的main包）提供的依赖——这些是库运行的基础，且必须和宿主版本对齐，避免重复打包或版本冲突。
• devDependencies：仅在库的开发、构建、测试阶段需要的工具/依赖，不会被打包进库产物，宿主项目完全不需要安装它们。
• dependencies：库自身运行时必须依赖、且宿主项目大概率不会自带（或不需要严格版本对齐）的第三方包，会被打包进库产物（或按需引入，取决于构建配置）。

划重点：不能全丢进dev和peer，得根据依赖的角色分类。

具体依赖分类示例 #

React相关 #

你的库是给React项目用的，React、ReactDOM这类核心框架必须放peerDependencies，同时可以在devDependencies里装一个具体版本用于本地开发调试，比如：

"peerDependencies": {
  "react": "^18.0.0",
  "react-dom": "^18.0.0"
},
"devDependencies": {
  "react": "^18.2.0",
  "react-dom": "^18.2.0"
}

这样既保证宿主提供兼容版本，又能在本地开发时用确定版本测试组件。

Lodash这类工具库 #

分两种情况：

• 如果你的库只用到lodash的个别方法，且构建时开启Tree Shaking（比如用Rollup或Vite），把lodash-es放进dependencies就行——它是运行时必须的，且宿主版本一般不会和你的库冲突（只要是兼容版本）。
• 如果你的库依赖lodash的整体功能，且担心宿主版本差异引发问题，也可以考虑放peerDependencies，但一般工具库放dependencies更稳妥，不会给宿主额外安装负担。

Babel、Webpack这类构建工具 #

必须丢进devDependencies——这些只是你开发和打包库的工具，和库的运行时半毛钱关系没有，宿主项目不需要它们，也绝对不能被打包进库产物。

通用依赖分类清单 #

放peerDependencies的场景 #

• 宿主项目必然会用的核心框架：React、Vue、Angular等
• 与宿主强绑定的工具：比如React Router（如果你的组件依赖路由功能，且宿主一定会装）
• 易引发版本冲突的核心依赖：比如Redux（如果你的组件依赖Redux的API，必须和宿主版本对齐）

放devDependencies的场景 #

• 构建工具：Babel、Webpack、Rollup、Vite、TypeScript（类型编译）
• 测试工具：Jest、React Testing Library、Cypress
• 代码规范工具：ESLint、Prettier、Stylelint
• 本地开发辅助：Storybook、Mock Service Worker

放dependencies的场景 #

• 库运行时必需、无版本冲突风险的工具库：lodash-es、date-fns、axios（如果你的组件封装了请求逻辑）
• 轻量、无框架依赖的第三方组件：比如纯JS的表单验证工具
• 与当前库强绑定的自封装子库（未单独发布的情况）

关键注意事项 #

• 别把peerDependencies里的依赖同时放进dependencies，否则会导致宿主重复安装，引发版本冲突。
• peerDependencies尽量设宽泛的版本范围（比如^18.0.0），提高兼容性。
• 构建库时确保Tree Shaking生效，只打包用到的代码，避免把dependencies里的包全部打包进去（ES模块格式更容易实现）。

内容的提问来源于stack exchange，提问作者Debapratim Chakraborty