依赖与版本约束

Monorepo 中最容易失控的是依赖版本。建议把运行环境、第三方依赖版本、内部包依赖关系分别处理。

Node.js 与 pnpm 版本

在根目录 package.json 中声明：

{
  "packageManager": "pnpm@11.10.0",
  "engines": {
    "node": ">=22.0.0",
    "pnpm": ">=11.0.0"
  }
}

• packageManager 声明推荐使用的包管理器及版本，通常配合 Corepack 使用。
• engines 声明 Node.js、pnpm 等运行环境的版本要求。
• packageManager 推荐使用精确版本，例如 "pnpm@11.10.0"，减少团队环境差异。

严格校验 engines

# .npmrc
engine-strict=true

开启后，当前 Node.js 或 pnpm 版本不满足 engines 时，安装依赖会失败。

统一第三方依赖版本

pnpm 可使用 catalog: 协议统一管理第三方依赖版本。

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

catalog:
  react: ^19.0.0
  react-dom: ^19.0.0
  typescript: ^5.0.0

子包中引用：

{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "typescript": "catalog:"
  }
}

这样升级 React、TypeScript 等公共依赖时，只需修改一处。

内部 package 依赖

Workspace 内部 package 之间建议使用 workspace: 协议：

{
  "name": "@vfan-monorepo/web",
  "dependencies": {
    "@vfan-monorepo/ui": "workspace:*",
    "@vfan-monorepo/utils": "workspace:*"
  }
}

workspace:* 表示该依赖必须从当前 Workspace 中解析。如果本地不存在对应 package，安装会失败，不会回退到 npm registry。

也可以使用：

{
  "dependencies": {
    "@vfan-monorepo/ui": "workspace:^",
    "@vfan-monorepo/utils": "workspace:~"
  }
}

发布 package 时，pnpm 会将 workspace: 版本转换为实际 semver 版本范围。

依赖声明原则

• 子包用到的依赖，必须声明在该子包中。
• 根目录只声明仓库级工具，不替子包隐式兜底。
• 共享库里的框架依赖通常放在 peerDependencies，避免和应用安装多份。
• 能用 catalog: 统一的公共依赖，优先在 pnpm-workspace.yaml 中集中维护。