peerdependencies 用于声明包所依赖但由宿主项目提供的共享依赖，适用于ui组件库、babel/eslint插件、类型定义扩展等场景，避免重复安装与版本冲突。
peerDependencies 用于声明你的包“期望宿主项目中已存在”的依赖，而不是自己安装一份。它解决的是插件、组件库、Babel 插件等场景中“和宿主共享同一份核心依赖”的问题，比如 React 组件库要求用户项目里已装 react 和 react-dom，而不是自己再装一套。
什么时候该用 peerDependencies？
典型适用场景包括：
- 你开发的是一个UI 组件库（如基于 React/Vue），需要用户项目提供框架本身；
- 你写的是Babel 插件、ESLint 插件、Webpack loader，它们必须和宿主工具链版本兼容；
- 你发布的是类型定义扩展包（如
@types/react的配套包），需与对应主包版本对齐； - 你想避免重复安装或版本冲突，比如两个子包各自装了不同版的
lodash，导致 bundle 增大或运行时行为不一致。
如何正确声明 peerDependencies？
在 package.json 中添加 peerDependencies 字段，格式和 dependencies 一样，但只写你期望宿主提供的包名与版本范围：
"peerDependencies": {
"react": "^18.0.0",
"react-dom": "^18.0.0",
"typescript": ">=4.9.0"
}
注意：
- 版本范围建议用
^或~，避免锁死（除非有强兼容约束）； - 不要把 peer 依赖同时写进
dependencies或devDependencies（否则 npm 可能自动安装，违背设计初衷）； - 如果你的包在开发时也需要这些依赖（比如跑测试、生成类型），应单独放进
devDependencies。
用户安装时会发生什么？
从 npm v7 开始，默认会自动检查并警告缺失或不匹配的 peer 依赖**：
- 用户执行
npm install your-lib时，如果项目里没装react或版本不满足^18.0.0，npm 会输出 WARNING； - 不会自动安装 peer 依赖 —— 这是关键：由用户自己决定是否安装、装哪个版本；
- 若用户强制忽略（
--legacy-peer-deps）或降级到 npm v6，则无警告，但隐患仍在。
因此，你应在文档中明确说明所需 peer 依赖及版本，例如：
# 安装前请确保： npm install react@^18.0.0 react-dom@^18.0.0
常见误区与建议
-
别把 runtime 依赖错标为 peer：如果包内部
require('lodash')且不假设宿主提供，就该放dependencies； - peer 不等于 optional：optionalDependencies 是可选安装、失败也不报错；peer 是“必须存在且版本合规”，否则可能运行出错；
- 测试环境要模拟真实 peer 场景：CI 中应创建最小宿主项目，安装你的包 + 指定 peer 版本，再跑用例；
- 使用
resolutions（yarn）或overrides（npm v8.3+）可强制统一 peer 版本，适合 monorepo 或复杂依赖树。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
