# Monorepo 依赖管理机制详解

## 1. Catalog 机制

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

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

### 使用方式
```yaml
# pnpm-workspace.yaml
catalog:
  react: ^19.1.0
  antd: ^5.26.3
  typescript: ^5.8.3
```

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

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

## 2. Workspace 依赖机制

### 什么是 workspace:*？
`"@vben/locales": "workspace:*"` 表示引用**同一个 monorepo 内的其他包**。

### workspace 协议说明
- `workspace:*` - 引用 workspace 内的包
- `workspace:^` - 引用 workspace 内包的兼容版本
- `workspace:~` - 引用 workspace 内包的补丁版本

### 使用场景
```json
// 子项目 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` 中：
```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 配置
```

### 依赖声明策略
```json
// 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 配置
```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 设置和扩展

### 配置示例
```json
{
  "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 开发和管理体系
- **关键点**：每个子项目仍需独立声明自己需要的依赖，无论是内部的还是外部的