pnpm Monorepo含本地工作区依赖的生产构建问题

核心问题定位 #

构建产物保留了本地工作区依赖的源码路径引用，而非指向部署目录node_modules中的安装包，导致部署后无法解析依赖。

分步解决方案 #

1. 确保工作区包的构建配置正确 #

每个工作区依赖包（如@ap/shared、@ap/service）需先完成生产构建，且package.json指定正确的产物入口：

// @ap/shared/package.json
{
  "name": "@ap/shared",
  "main": "./build/index.js", // 指向构建后的产物文件
  "types": "./build/index.d.ts",
  "scripts": {
    "build": "tsc --project tsconfig.prod.json" // 使用生产专属配置构建
  }
}

如果用TypeScript做构建，要避免生产模式下保留paths字段的本地源码映射，可借助tsconfig-paths-webpack-plugin（Webpack）或vite-tsconfig-paths（Vite）的生产配置，自动将路径解析为node_modules中的依赖。

2. 调整部署流程：先构建依赖，再部署服务 #

不要直接部署源码，先构建所有关联的工作区包，再部署目标服务的构建产物：

# 1. 构建所有工作区依赖包
pnpm --filter=@ap/shared build
pnpm --filter=@ap/service build
pnpm --filter=@ap/server build

# 2. 构建目标服务
pnpm --filter=@ap/auth-service build

# 3. 部署构建后的服务到生产目录
pnpm --filter=@ap/auth-service --prod deploy @prod/auth-service

3. 强制使用已构建的工作区包（未发布到仓库场景） #

如果工作区包没推送到私有/公共仓库，可通过pnpm pack打包为tarball，再在部署目录安装本地包：

# 进入依赖包目录打包
cd packages/shared
pnpm pack

# 创建部署目录的本地依赖文件夹并复制tarball
mkdir -p @prod/auth-service/local-packages
mv ap-shared-*.tgz @prod/auth-service/local-packages/

# 在部署目录安装本地依赖包
cd @prod/auth-service
pnpm add file:local-packages/ap-shared-*.tgz @ap/service@file:../local-packages/ap-service-*.tgz

4. 调整pnpm工作区配置避免源码优先引用 #

检查pnpm-workspace.yaml，如果部署目录@prod在工作区内，会导致pnpm优先引用本地源码，建议将@prod移出工作区，或部署时添加--no-workspace参数：

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  # 移除或注释掉 '@prod/*'，避免部署目录被识别为工作区包

或修改部署命令：

pnpm --filter=@ap/auth-service --prod --no-workspace deploy @prod/auth-service

5. 验证构建产物的依赖引用 #

构建完成后，检查部署目录的构建文件，确认依赖路径是否指向node_modules：

# 检查构建产物中的@ap/shared引用路径
grep -r "@ap/shared" @prod/auth-service/build

如果输出仍包含本地源码路径（如../../packages/shared），需重新调整构建工具的生产配置，确保依赖解析到node_modules。

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