多工作区npm项目打包为单个包后依赖缺失问题排查

核心原因 #

npm默认的npm pack只会处理根目录的配置和文件，不会自动包含工作区内容，也不会合并工作区的依赖到根package.json。而npm pack -ws是单独打包每个工作区，不符合你需要单个包的需求。

解决步骤 #

1. 合并工作区的生产依赖到根package.json #

遍历workspace-1、workspace-2的package.json，将它们的dependencies字段内容合并到根目录的package.json的dependencies中：

• 相同依赖取统一版本号（优先兼容范围大的版本，或协调成一致版本）
• 仅合并生产依赖（dependencies），开发依赖（devDependencies）无需合并，外部项目安装时不需要这些

示例：
如果workspace-1的package.json有：

"dependencies": {
  "lodash": "^4.17.21"
}

workspace-2的package.json有：

"dependencies": {
  "axios": "^1.6.0",
  "lodash": "^4.17.20"
}

根package.json的dependencies应调整为：

"dependencies": {
  "lodash": "^4.17.21",
  "axios": "^1.6.0"
}

2. 配置根package.json的files字段，包含工作区内容 #

在根package.json中添加files字段，指定要打包的工作区文件，确保工作区源码被包含到最终包中：

"files": [
  "workspace-1/**/*",
  "workspace-2/**/*"
]

注意：如果工作区目录下有.gitignore或npmignore，要确保源码文件不会被排除；工作区的node_modules会自动被npm忽略，无需额外配置。

3. 替换工作区之间的内部依赖引用 #

如果工作区之间存在相互依赖（比如workspace-1依赖workspace-2），本地开发时用的workspace:*协议在外部项目无法解析，需要修改为相对路径：
比如workspace-1的package.json中原来的：

"dependencies": {
  "workspace-2": "workspace:*"
}

改为相对路径：

"dependencies": {
  "workspace-2": "../workspace-2"
}

同时确保代码中的模块引用路径能在打包后的目录结构下正常找到对应文件。

4. 执行打包并测试 #

在项目根目录执行：

npm pack

生成的.tgz包会包含两个工作区的源码和合并后的依赖配置。将这个包安装到其他项目：

npm install /path/to/your-project.tgz

此时node_modules会安装所有生产依赖，工作区代码也能正常引用。

额外提示 #

• 如果项目需要构建（比如编译TS、打包前端资源），建议先在每个工作区执行构建命令，再将构建产物目录添加到根package.json的files字段中，而非打包源码。
• 若工作区结构复杂，可写脚本自动合并依赖和调整配置，减少手动操作的出错率。

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