如何部署依赖其他工作区及包的单个npm工作区？

问题背景 #

我基于npm workspaces和TypeScript Project References搭建了项目，开发阶段运行正常：所有node_modules集中在根目录，通过符号链接实现内部包间直接引用。但部署时遇到两个核心问题：

• 构建生成的dist目录仅包含业务代码，没有依赖文件
• 单独部署某个工作区时，执行npm i会自动安装所有工作区的依赖并创建全部符号链接，导致冗余

项目目录结构：

├── node_modules/
├── package-lock.json
├── package.json
├── packages
│   ├── package-1
│   │   ├── dist
│   │   │   ├── helper.d.ts
│   │   │   ├── helper.js
│   │   │   ├── helper.js.map
│   │   │   ├── main.d.ts
│   │   │   ├── main.js
│   │   │   └── main.js.map
│   │   ├── package.json
│   │   ├── src
│   │   │   ├── helper.ts
│   │   │   └── main.ts
│   │   └── tsconfig.json
│   └── package-2
│       ├── dist
│       │   ├── index.d.ts
│       │   ├── index.js
│       │   └── index.js.map
│       ├── package.json
│       ├── src
│       │   └── index.ts
│       └── tsconfig.json
├── tsconfig.build.json
└── tsconfig.json

解决方案 #

1. 确保工作区构建产物的正确性 #

首先，每个工作区的package.json必须正确配置入口字段，指向构建后的产物：

// packages/package-2/package.json
{
  "name": "@yourscope/package-2",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "version": "1.0.0",
  // 仅保留自身的生产依赖，比如依赖package-1的话：
  "dependencies": {
    "@yourscope/package-1": "^1.0.0"
  }
}

然后按依赖顺序构建工作区（比如package-2依赖package-1，先构建package-1）：

# 从根目录执行，构建依赖的工作区
tsc -b packages/package-1
# 构建目标工作区
tsc -b packages/package-2

2. 生成单工作区的独立部署包 #

方法一：用npm pack快速打包

进入目标工作区目录，执行打包命令：

cd packages/package-2
npm pack

这会生成一个类似@yourscope/package-2-1.0.0.tgz的压缩包，包含：

• 完整的dist构建产物
• 仅含自身生产依赖的package.json
• 项目必要的元文件（如README、LICENSE）

部署时，在目标环境解压该压缩包，执行：

npm install --production

只会安装该工作区所需的生产依赖，不会拉取其他工作区内容。

方法二：手动整理部署文件

1. 创建临时目录，复制目标工作区的dist目录、package.json到该目录
2. 编辑临时目录的package.json：
   • 移除任何workspaces相关配置
   • 确保dependencies仅保留该工作区实际需要的包（包括内部包的正确版本）
3. 如果内部包未发布到npm，需将内部包的dist产物复制到临时目录的node_modules/@yourscope/package-1下，或先发布到私有npm仓库再安装

3. 本地测试单工作区独立安装 #

如果需要在本地验证单工作区的依赖安装，可使用npm的--workspace参数指定仅处理目标工作区：

# 仅安装package-2的生产依赖，在package-2目录生成独立node_modules
npm install --production --workspace=packages/package-2

此命令不会安装其他工作区的依赖，也不会创建跨工作区的符号链接。

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