pnpm Monorepo工作区共享依赖与二进制文件高效管理问询

问题描述 #

背景 #

• 共享依赖：维护一套跨项目通用依赖，避免每个package.json重复声明，保证版本一致性
• 二进制文件解析：rimraf等依赖的二进制文件需在单个项目脚本中可用，无论定义在共享包还是根配置中
• 避免冗余：不让所有项目或根package.json包含不必要的依赖
• 模块化配置：集中管理共享配置与依赖，按需关联给单个项目使用

当前配置 #

pnpm-workspaces.yaml

packages:
  - "packages/*"
  - "packages-foo/*"
  - "packages-bar/*"

根package.json

{
  "name": "monorepo-root",
  "devDependencies": {
    "eslint": "^7.32.0",
    "prettier": "^2.3.2",
    "rimraf": "^3.0.2"
  }
}

共享配置包package.json（packages/shared/package.json）

{
  "name": "shared-config",
  "devDependencies": {
    "@faker-js/faker": "^7.4.0",
    "typescript": "^5.5.3"
  }
}

API包package.json（packages/api/package.json）

{
  "name": "api-package",
  "scripts": {
    "build": "pnpm exec rimraf dist && pnpm exec tsc",
    "lint": "pnpm exec eslint src --fix"
  },
  "devDependencies": {
    "typescript": "workspace:*"
  }
}

Web包package.json（packages/web/package.json）

{
  "name": "web-package",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "build": "pnpm exec rimraf dist && pnpm exec tsc",
    "lint": "pnpm exec eslint src --fix"
  },
  "devDependencies": {
    "typescript": "workspace:*"
  }
}

遇到的问题 #

• 二进制文件未找到：单个包运行脚本时，必须在该包的devDependencies中显式列出rimraf等依赖，否则无法找到对应的二进制文件
• 共享库无法解析：shared-config包中的@faker-js/faker无法被api-package等其他包识别并导入

疑问 #

1. 如何确保共享依赖中的二进制文件在单个包脚本中正确解析并执行？
2. 如何以最优方式管理共享依赖，避免重复与冗余，同时确保需要时可用？
3. pnpm workspaces是否有处理此类问题的最佳实践或配置？
4. pnpm workspaces能否实现上述需求，还是需求不可行？

解决方案 #

你的需求完全可以通过pnpm Workspaces实现，以下是针对性的配置方案与最佳实践：

1. 解决二进制文件无法解析的问题 #

pnpm默认不会自动将根目录或其他包的二进制文件暴露给子包，可通过两种方式处理：

方式一：从根目录通过--filter执行子包脚本

如果不需要在子包本地直接调用二进制文件，可在根目录运行子包脚本，此时会自动使用根目录的依赖：

# 在根目录执行api包的build脚本
pnpm --filter api-package build

方式二：将根依赖"链接"到子包（无冗余安装）

使用pnpm add的--workspace参数，将根目录的依赖关联到子包，不会重复安装依赖文件：

# 为api-package关联根目录的rimraf、eslint
pnpm add rimraf eslint --save-dev --workspace --filter api-package

执行后，api-package的devDependencies会变为：

{
  "devDependencies": {
    "eslint": "workspace:^7.32.0",
    "rimraf": "workspace:^3.0.2",
    "typescript": "workspace:*"
  }
}

此时子包脚本直接调用pnpm exec rimraf即可正常执行，依赖实际存储在根目录的node_modules中，无冗余。

2. 解决共享包依赖无法被其他包解析的问题 #

当前shared-config的依赖声明在自身的devDependencies中，其他包无法访问。需调整依赖声明方式：

步骤1：修改shared-config的package.json

将需要共享的依赖从devDependencies移到dependencies（生产依赖场景）或结合peerDependencies（开发工具类场景），同时确保包版本可被识别：

{
  "name": "shared-config",
  "version": "1.0.0",
  "dependencies": {
    "@faker-js/faker": "^7.4.0"
  },
  "devDependencies": {
    "typescript": "^5.5.3"
  },
  "peerDependencies": {
    "typescript": "^5.5.3"
  }
}

步骤2：在目标子包中引入shared-config

pnpm add shared-config --save-dev --workspace --filter api-package

此时api-package的package.json会添加：

{
  "devDependencies": {
    "shared-config": "workspace:*",
    "typescript": "workspace:*"
  }
}

现在api-package中即可正常导入@faker-js/faker，pnpm会自动解析shared-config的依赖树。

3. 最佳实践：分层管理共享依赖 #

• 根目录：存放所有子包都需要的通用开发工具（如eslint、prettier、rimraf），通过--filter关联到需要的子包
• 共享配置包：存放特定场景的共享依赖（如业务mock工具@faker-js/faker、框架配置），作为子包的依赖引入
• 子包：仅声明自身独有的依赖，通过workspace:*关联根或共享包的依赖

4. 额外配置优化 #

在根目录的.npmrc中添加以下配置，优化workspace的依赖解析：

# 将指定工具类依赖提升到公共目录，让所有子包可直接访问二进制
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*
public-hoist-pattern[]=*rimraf*
# 自动安装peer依赖
auto-install-peers=true

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