NPM Workspaces安装依赖时根目录与工作区node_modules存放规则咨询

架构老林

2026-9-26

NPM Workspaces 依赖安装位置判定规则

默认依赖提升规则
NPM默认开启依赖提升（Hoist）机制，会先统一比对所有工作区声明的依赖版本：只要多个工作区依赖的同一包版本满足语义化版本兼容要求，就会将该依赖安装到根目录node_modules，供所有工作区共用，减少重复安装体积。
版本冲突场景
不同工作区依赖的同一包版本无法兼容时，被引用次数更多、下载量更高的版本会被提升到根目录node_modules，其余不兼容版本会直接安装到对应依赖的工作区node_modules目录下。
根目录显式声明的依赖
直接写在根目录package.json的dependencies、devDependencies字段中的依赖，无论工作区是否引用，都会统一安装到根目录node_modules。
工作区单独安装的依赖
通过npm install <包名> -w <工作区名称>命令单独为某一工作区安装依赖时，若该依赖版本和其余工作区的依赖无冲突，会自动提升到根目录；存在版本冲突则保留在对应工作区的node_modules中。
手动配置禁用提升的场景
若在根目录.npmrc中配置了hoist=false全局禁用提升，或是通过nohoist字段指定了特定包不参与提升，这些包无论版本是否兼容，都会直接安装到对应工作区的node_modules下，不会被提升到根目录。
Peer依赖适配场景
若某依赖要求的Peer依赖版本和根目录已安装的对应包版本不匹配，NPM会将该依赖直接安装到对应工作区的node_modules中，避免Peer依赖版本报错。