在 monorepo 项目中配置 npm workspace,需要在根目录的 package.json 中声明 workspaces 字段并指定子包路径。执行 npm install 后,npm 会自动将各工作区的依赖扁平化安装到根目录的 node_modules 中,实现依赖共享和统一版本管理。

如何定义工作区的路径模式
通过 workspaces 数组配置 glob 表达式来匹配子目录。例如设置 ["packages/*"] 可自动包含所有直接位于 packages 文件夹下的子项目。这种配置方式让 npm 在解析时能准确识别哪些文件夹是独立的工作区。

{
"name": "root-monorepo",
"private": true,
"workspaces": [
"packages/*"
]
}
上述配置使 packages/utils 和 packages/app 成为两个独立工作区。运行 npm install 会在根目录生成 node_modules,并将公共依赖链接至此。各子包的 package.json 无需额外配置即可引用根级安装的模块。
如何在不同工作区间共享依赖
工作区间的依赖共享依赖于 npm 的 hoisting 机制。当多个子包依赖同一库的不同版本时,npm 会尝试合并;若版本冲突,则保留各自隔离的版本。开发者可通过 npm ls 查看依赖树结构,确认模块是否被提升(hoisted)至根目录。

// packages/app/package.json
{
"name": "@my/app",
"dependencies": {
"lodash": "^4.17.0"
}
}
// packages/utils/package.json
{
"name": "@my/utils",
"dependencies": {
"lodash": "^4.17.0"
}
}
在此示例中,两个子包均依赖 lodash。由于版本范围兼容,npm 会将 lodash 安装至根 node_modules,并通过符号链接供各子包使用。若 utils 改为依赖 lodash@3.x,则根目录保留 4.x,而 utils 目录下会出现独立的 3.x 版本实例。
workspace:协议在跨包引用中如何使用
当子包需要直接依赖另一个子包时,需在 package.json 中使用 workspace: 协议。该协议告诉 npm 从本地工作区解析依赖,而非从远程 registry 下载。这确保了开发过程中对内部模块的修改能即时生效,无需发布中间版本。
{
"name": "@my/app",
"dependencies": {
"@my/utils": "workspace:*"
}
}
此配置使 @my/app 能够直接调用 @my/utils 导出的功能。npm 会在安装阶段建立指向 packages/utils 的符号链接。无论工作区层级多深,只要路径匹配且协议正确,跨包引用即可稳定运行。若未使用此协议而直接写版本号,npm 会尝试从网络获取,导致本地开发调试失败。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南











