|
|
@@ -0,0 +1,204 @@
|
|
|
+# 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 开发和管理体系
|
|
|
+- **关键点**：每个子项目仍需独立声明自己需要的依赖，无论是内部的还是外部的
|
