monorepo_react/monorepo-dependency-management.md

Monorepo 依赖管理机制详解

1. Catalog 机制

什么是 Catalog？

Catalog 是 pnpm 提供的一种版本管理机制，用于在 monorepo 中统一管理依赖版本。

Catalog 的作用

• 版本统一：确保整个 monorepo 中相同依赖使用相同版本
• 集中管理：在 pnpm-workspace.yaml 中统一定义所有依赖版本
• 避免冲突：防止不同子项目使用不同版本的同一依赖

使用方式

# pnpm-workspace.yaml
catalog:
  react: ^19.1.0
  antd: ^5.26.3
  typescript: ^5.8.3

// 子项目 package.json
{
  "dependencies": {
    "react": "catalog:",
    "antd": "catalog:"
  }
}

优势

• ✅ 版本一致性
• ✅ 集中管理
• ✅ 避免重复定义版本
• ❌ 不是依赖共享，每个子项目仍需独立声明依赖

2. Workspace 依赖机制

什么是 workspace:*？

"@vben/locales": "workspace:*" 表示引用同一个 monorepo 内的其他包。

workspace 协议说明

• workspace:* - 引用 workspace 内的包
• workspace:^ - 引用 workspace 内包的兼容版本
• workspace:~ - 引用 workspace 内包的补丁版本

使用场景

// 子项目 A 的 package.json
{
  "dependencies": {
    "@monorepo/ui": "workspace:*",           // 引用内部 UI 包
    "@monorepo/utils": "workspace:*",        // 引用内部工具包
    "react": "catalog:"                      // 引用外部依赖
  }
}

实际例子

假设你的项目结构：

monorepo/
├── packages/
│   ├── ui/           # @monorepo/ui
│   └── utils/        # @monorepo/utils
└── apps/
    └── admin/        # 需要引用 ui 和 utils

在 apps/admin/package.json 中：

{
  "dependencies": {
    "@monorepo/ui": "workspace:*",      // 引用内部 UI 包
    "@monorepo/utils": "workspace:*",   // 引用内部工具包
    "react": "catalog:"                 // 外部依赖使用 catalog
  }
}

3. 两种机制的区别

特性	Catalog	Workspace
用途	版本管理	内部包引用
作用范围	外部依赖	内部包
语法	"catalog:"	"workspace:*"
定义位置	pnpm-workspace.yaml	各包的 package.json
依赖来源	npm registry	本地 workspace

4. 最佳实践

推荐的项目结构

monorepo/
├── packages/
│   ├── ui/                    # 共享 UI 组件
│   ├── utils/                 # 共享工具函数
│   └── types/                 # 共享类型定义
├── apps/
│   ├── admin/                 # 管理后台
│   └── user/                  # 用户端
└── pnpm-workspace.yaml        # workspace 配置

依赖声明策略

// apps/admin/package.json
{
  "dependencies": {
    // 内部包使用 workspace
    "@monorepo/ui": "workspace:*",
    "@monorepo/utils": "workspace:*",
    "@monorepo/types": "workspace:*",
    
    // 外部依赖使用 catalog
    "react": "catalog:",
    "antd": "catalog:",
    "axios": "catalog:"
  }
}

pnpm-workspace.yaml 配置

packages:
  - packages/*
  - apps/*

catalog:
  # 外部依赖版本管理
  react: ^19.1.0
  antd: ^5.26.3
  typescript: ^5.8.3

5. VS Code Workspace 文件

什么是 .code-workspace 文件？

.code-workspace 文件是 VS Code 的多根工作区配置文件，用于管理包含多个项目文件夹的工作区。

在 Monorepo 中的作用

• 多根工作区：将 monorepo 中的多个包作为独立的工作区根目录
• 统一管理：在一个 VS Code 窗口中管理整个 monorepo
• 独立配置：每个包可以有独立的 VS Code 设置和扩展

配置示例

{
  "folders": [
    {
      "name": "Root",
      "path": "."
    },
    {
      "name": "UI Package",
      "path": "./packages/ui"
    },
    {
      "name": "Admin App",
      "path": "./apps/purchase-admin"
    },
    {
      "name": "Internal Tools",
      "path": "./internal"
    }
  ],
  "settings": {
    "typescript.preferences.includePackageJsonAutoImports": "on",
    "eslint.workingDirectories": [
      "packages/ui",
      "apps/purchase-admin"
    ]
  },
  "extensions": {
    "recommendations": [
      "ms-vscode.vscode-typescript-next",
      "esbenp.prettier-vscode",
      "dbaeumer.vscode-eslint"
    ]
  }
}

优势

• ✅ 统一开发环境：所有包在同一个窗口中
• ✅ 智能提示：跨包的类型提示和自动补全
• ✅ 统一配置：共享 ESLint、Prettier 等配置
• ✅ 调试支持：可以调试整个 monorepo 的代码
• ✅ Git 集成：统一的版本控制管理

使用方式

1. 在 VS Code 中打开 .code-workspace 文件
2. 或者使用命令：code zw-admin.code-workspace
3. VS Code 会自动加载所有配置的文件夹

6. 总结

• Catalog：用于管理外部依赖版本，确保版本一致性
• Workspace：用于引用内部包，实现代码共享
• VS Code Workspace：提供统一的开发环境和配置管理
• 三者结合：构建完整的 monorepo 开发和管理体系
• 关键点：每个子项目仍需独立声明自己需要的依赖，无论是内部的还是外部的