# Monorepo 架构设计

<cite>
**本文引用的文件**
- [package.json](file://package.json)
- [pnpm-workspace.yaml](file://pnpm-workspace.yaml)
- [turbo.json](file://turbo.json)
- [vite.config.js](file://vite.config.js)
- [ARCHITECTURE_SUMMARY.md](file://ARCHITECTURE_SUMMARY.md)
- [MIGRATION.md](file://MIGRATION.md)
- [packages/core/package.json](file://packages/core/package.json)
- [packages/core/vite.config.js](file://packages/core/vite.config.js)
- [packages/core/src/index.js](file://packages/core/src/index.js)
- [packages/adapters/view-ui-plus/package.json](file://packages/adapters/view-ui-plus/package.json)
- [packages/adapters/element-plus/package.json](file://packages/adapters/element-plus/package.json)
- [packages/compat/package.json](file://packages/compat/package.json)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 引言
本文件面向 Pro-IVIEW V3 的 Monorepo 架构设计，围绕 pnpm workspace 与 Turborepo 的协同工作机制展开，系统阐述包管理策略、依赖解析与版本锁定、任务依赖图与增量构建、缓存优化策略，以及多包管理带来的独立构建、版本控制与发布流程优势。同时提供包结构规划指南（命名规范、目录组织、依赖关系管理），并结合仓库中的真实配置文件给出可操作的最佳实践与实施路径。

## 项目结构
仓库采用 Monorepo 分层组织，以 pnpm workspace 管理多包，Turborepo 提供跨包构建缓存与任务编排能力。顶层通过脚本统一调度，各子包拥有独立的构建配置与依赖声明，形成“核心逻辑解耦、UI 适配可插拔”的架构。

```mermaid
graph TB
Root["根目录<br/>package.json / pnpm-workspace.yaml / turbo.json / vite.config.js"]
Core["@pro-iview/core<br/>核心包"]
AdapterVUE["@pro-iview/view-ui-plus<br/>UI 适配器"]
AdapterEP["@pro-iview/element-plus<br/>UI 适配器"]
Compat["pro_iview_v3<br/>向后兼容包"]
Root --> Core
Root --> AdapterVUE
Root --> AdapterEP
Root --> Compat
Compat --> Core
Compat --> AdapterVUE
```

图表来源
- [package.json:1-47](file://package.json#L1-L47)
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [packages/core/package.json:1-46](file://packages/core/package.json#L1-L46)
- [packages/adapters/view-ui-plus/package.json:1-34](file://packages/adapters/view-ui-plus/package.json#L1-L34)
- [packages/adapters/element-plus/package.json:1-34](file://packages/adapters/element-plus/package.json#L1-L34)
- [packages/compat/package.json:1-33](file://packages/compat/package.json#L1-L33)

章节来源
- [package.json:1-47](file://package.json#L1-L47)
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [vite.config.js:1-100](file://vite.config.js#L1-L100)
- [ARCHITECTURE_SUMMARY.md:59-120](file://ARCHITECTURE_SUMMARY.md#L59-L120)

## 核心组件
- pnpm workspace：通过工作区配置声明包范围，启用链接式安装与共享节点缓存，减少磁盘占用并提升安装速度。
- Turborepo：通过任务管线定义构建依赖与输出产物，利用远程/本地缓存加速重复构建，支持增量构建与持久化任务。
- Vite 构建链路：各包独立构建，核心包导出 ESM/UMD，适配器包导出对应 UI 库的适配实现，兼容包聚合核心与适配器。
- 适配器模式：核心包不直接依赖具体 UI 库，通过依赖注入机制在运行时绑定 UI 适配器，实现对 view-ui-plus 与 element-plus 的无缝切换。

章节来源
- [package.json:8-18](file://package.json#L8-L18)
- [turbo.json:3-16](file://turbo.json#L3-L16)
- [packages/core/vite.config.js:1-31](file://packages/core/vite.config.js#L1-L31)
- [packages/core/src/index.js:13-31](file://packages/core/src/index.js#L13-L31)

## 架构总览
下图展示 Monorepo 的整体交互：根脚本驱动 Turborepo 执行构建；各包通过 Vite 输出产物；核心包通过适配器注入机制与 UI 适配器协作；兼容包将核心与适配器组合，维持向后兼容。

```mermaid
graph TB
subgraph "根层"
Scripts["脚本(dev/build)<br/>package.json"]
Turbo["任务管线<br/>turbo.json"]
RootVite["根级构建配置<br/>vite.config.js"]
end
subgraph "核心与适配"
Core["@pro-iview/core<br/>核心包"]
AdapterVUE["@pro-iview/view-ui-plus<br/>适配器"]
AdapterEP["@pro-iview/element-plus<br/>适配器"]
Compat["pro_iview_v3<br/>兼容包"]
end
Scripts --> Turbo
Turbo --> Core
Turbo --> AdapterVUE
Turbo --> AdapterEP
Turbo --> Compat
RootVite -.-> Core
RootVite -.-> AdapterVUE
RootVite -.-> AdapterEP
RootVite -.-> Compat
Compat --> Core
Compat --> AdapterVUE
```

图表来源
- [package.json:8-18](file://package.json#L8-L18)
- [turbo.json:3-16](file://turbo.json#L3-L16)
- [vite.config.js:1-100](file://vite.config.js#L1-L100)
- [packages/core/package.json:1-46](file://packages/core/package.json#L1-L46)
- [packages/adapters/view-ui-plus/package.json:1-34](file://packages/adapters/view-ui-plus/package.json#L1-L34)
- [packages/adapters/element-plus/package.json:1-34](file://packages/adapters/element-plus/package.json#L1-L34)
- [packages/compat/package.json:1-33](file://packages/compat/package.json#L1-L33)

## 详细组件分析

### pnpm workspace 配置与包管理策略
- 工作区范围：通过通配符声明核心包、适配器集合与兼容包，确保 pnpm 将其识别为同一工作区内的成员。
- 依赖解析与版本锁定：pnpm 采用 deterministic linking 与 node_modules 结构，避免重复安装；版本锁定由根层 packageManager 字段与 lockfile 共同保证。
- 独立构建与发布：各包拥有独立的 package.json 与构建配置，可按需独立构建与发布，降低耦合度。

章节来源
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [package.json:46-47](file://package.json#L46-L47)
- [packages/core/package.json:1-46](file://packages/core/package.json#L1-L46)
- [packages/adapters/view-ui-plus/package.json:1-34](file://packages/adapters/view-ui-plus/package.json#L1-L34)
- [packages/adapters/element-plus/package.json:1-34](file://packages/adapters/element-plus/package.json#L1-L34)
- [packages/compat/package.json:1-33](file://packages/compat/package.json#L1-L33)

### Turborepo 构建缓存与任务编排
- 任务依赖图：构建任务 dependsOn 指定上游依赖，实现自顶向下或拓扑有序执行，确保产物一致性。
- 输出产物：通过 outputs 定义产物目录，Turborepo 将其纳入缓存键的一部分，避免误命中。
- 缓存策略：dev 任务禁用缓存并持久化，利于开发体验；build 任务启用缓存，结合远程缓存可显著缩短 CI 时间。
- 过滤执行：通过过滤器仅构建指定包，提高迭代效率。

```mermaid
flowchart TD
Start(["开始"]) --> ReadPipeline["读取任务管线<br/>turbo.json"]
ReadPipeline --> PlanTasks["计划任务依赖图"]
PlanTasks --> ExecBuild{"执行构建？"}
ExecBuild --> |是| CacheCheck["检查缓存命中"]
ExecBuild --> |否| Skip["跳过任务"]
CacheCheck --> Hit{"缓存命中？"}
Hit --> |是| Restore["恢复产物"]
Hit --> |否| RunBuild["执行构建"]
RunBuild --> WriteCache["写入缓存"]
Restore --> Done(["结束"])
WriteCache --> Done
Skip --> Done
```

图表来源
- [turbo.json:3-16](file://turbo.json#L3-L16)

章节来源
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [package.json:8-18](file://package.json#L8-L18)

### 核心包（@pro-iview/core）构建与适配器注入
- 构建配置：核心包使用 Vite 构建 ESM 与 UMD 两种格式，入口指向 src/index.js，Rollup 外部化 Vue，避免将运行时框架打包进库。
- 适配器注入：通过 provideUIAdapter 将 UI 适配器注入到应用上下文，组件通过 useUIAdapter 获取 UI 组件，实现与 UI 库解耦。
- 产物与导出：通过 exports 字段声明 ESM/UMD 与类型文件，files 字段限定发布内容，确保 npm 发布精简且规范。

```mermaid
sequenceDiagram
participant App as "应用"
participant Core as "@pro-iview/core"
participant Adapter as "UI 适配器"
participant Vue as "Vue 应用"
App->>Core : "install(app, { adapter })"
Core->>Core : "provideUIAdapter(adapter)"
Core->>Adapter : "adapter.install(app)?"
Core->>Vue : "注册全局组件/指令"
Note over Core,Adapter : "运行时通过 inject 获取 UI 组件"
```

图表来源
- [packages/core/src/index.js:13-31](file://packages/core/src/index.js#L13-L31)
- [packages/core/vite.config.js:10-24](file://packages/core/vite.config.js#L10-L24)
- [packages/core/package.json:8-18](file://packages/core/package.json#L8-L18)

章节来源
- [packages/core/src/index.js:1-85](file://packages/core/src/index.js#L1-L85)
- [packages/core/vite.config.js:1-31](file://packages/core/vite.config.js#L1-L31)
- [packages/core/package.json:1-46](file://packages/core/package.json#L1-L46)

### UI 适配器（view-ui-plus 与 element-plus）
- 适配器职责：将核心包中抽象的 UI 接口映射到具体 UI 库组件与 API（如 Message），并可提供样式映射与图标兼容层。
- 依赖声明：适配器包声明 peerDependencies，要求宿主应用显式安装目标 UI 库，避免重复打包与版本冲突。
- 构建产物：适配器同样导出 ESM/UMD 与类型文件，便于在不同环境中使用。

章节来源
- [packages/adapters/view-ui-plus/package.json:1-34](file://packages/adapters/view-ui-plus/package.json#L1-L34)
- [packages/adapters/element-plus/package.json:1-34](file://packages/adapters/element-plus/package.json#L1-L34)

### 向后兼容包（pro_iview_v3）
- 组合策略：兼容包内部依赖核心包与 view-ui-plus 适配器，自动集成适配器，保持原有 API 不变。
- 适用场景：老项目零成本升级，无需修改业务代码即可迁移到新架构。

章节来源
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)
- [MIGRATION.md:69-81](file://MIGRATION.md#L69-L81)

### 根级构建与脚本
- 根脚本：dev 与 build 统一走 Turborepo；lib/build:core/build:adapter:* 提供定向构建与过滤。
- 根级 Vite：用于文档与示例构建，entry 指向 packages/index.js，配合外部化策略与复制插件处理国际化资源。

章节来源
- [package.json:8-18](file://package.json#L8-L18)
- [vite.config.js:11-88](file://vite.config.js#L11-L88)

## 依赖分析
- 依赖注入：核心包通过 provide/inject 解耦 UI 组件来源，组件在运行时通过 useUIAdapter 获取 UI 组件，避免在编译期绑定具体 UI 库。
- peerDependencies：适配器声明 peerDependencies，确保宿主应用自行管理 UI 库版本，避免重复打包与版本漂移。
- workspace:*：兼容包对核心与适配器使用 workspace:*，在本地开发时指向工作区内对应包，提升联调效率。

```mermaid
graph LR
Core["@pro-iview/core"] -- "peerDependencies: vue" --> Vue["vue"]
AdapterVUE["@pro-iview/view-ui-plus"] -- "peerDependencies: vue, view-ui-plus" --> Vue
AdapterVUE -- "peerDependencies: vue, view-ui-plus" --> VUEPlus["view-ui-plus"]
AdapterEP["@pro-iview/element-plus"] -- "peerDependencies: vue, element-plus" --> EP["element-plus"]
Compat["pro_iview_v3"] -- "workspace:*" --> Core
Compat -- "workspace:*" --> AdapterVUE
```

图表来源
- [packages/core/package.json:43-45](file://packages/core/package.json#L43-L45)
- [packages/adapters/view-ui-plus/package.json:30-33](file://packages/adapters/view-ui-plus/package.json#L30-L33)
- [packages/adapters/element-plus/package.json:30-33](file://packages/adapters/element-plus/package.json#L30-L33)
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)

章节来源
- [packages/core/package.json:43-45](file://packages/core/package.json#L43-L45)
- [packages/adapters/view-ui-plus/package.json:30-33](file://packages/adapters/view-ui-plus/package.json#L30-L33)
- [packages/adapters/element-plus/package.json:30-33](file://packages/adapters/element-plus/package.json#L30-L33)
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)

## 性能考虑
- 安装性能：pnpm workspace 通过符号链接与共享缓存减少磁盘占用与网络请求，提升安装速度。
- 构建性能：Turborepo 任务依赖图与缓存键包含 outputs，避免重复构建；dev 任务持久化可减少冷启动时间。
- 产物体积：核心包 external Vue，适配器仅导出必要实现，避免重复打包第三方库。
- CI 加速：结合远程缓存与增量构建，显著缩短流水线时间。

## 故障排查指南
- 依赖未解析或版本冲突：确认 peerDependencies 是否满足，避免在 node_modules 中出现重复版本。
- 本地联调异常：检查 compat 包是否使用 workspace:* 指向本地核心与适配器，避免发布版本干扰。
- 构建失败：核对 turbo.json 的 dependsOn 与 outputs 是否覆盖当前包产物；检查 Vite external 与 globals 配置是否与运行环境一致。
- 文档/示例构建问题：确认根级 vite.config.js 的 envDir 与外部化列表是否匹配实际依赖。

章节来源
- [turbo.json:3-16](file://turbo.json#L3-L16)
- [vite.config.js:14-88](file://vite.config.js#L14-L88)
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)

## 结论
Pro-IVIEW V3 的 Monorepo 架构以 pnpm workspace 与 Turborepo 为核心，结合适配器模式实现核心逻辑与 UI 库的彻底解耦。该方案在多包管理、独立构建、版本控制与发布流程方面具备显著优势，同时通过缓存与增量构建提升开发与 CI 效率。遵循本文的包结构规划与最佳实践，可帮助团队高效落地并持续演进该架构。

## 附录

### 包结构规划指南
- 命名规范：核心包使用 @pro-iview/core，适配器包使用 @pro-iview/<ui-lib>，兼容包使用 pro_iview_v3，保持清晰的语义边界。
- 目录组织：核心包集中存放组件、mixin、libs、locale、directive 与 ui-adapter；适配器包聚焦 UI 映射与 API 统一；兼容包聚合核心与适配器。
- 依赖关系管理：核心包仅声明 peerDependencies 与运行时依赖；适配器声明 peerDependencies 对应 UI 库；兼容包使用 workspace:* 指向本地包。

章节来源
- [ARCHITECTURE_SUMMARY.md:59-120](file://ARCHITECTURE_SUMMARY.md#L59-L120)
- [packages/core/package.json:43-45](file://packages/core/package.json#L43-L45)
- [packages/adapters/view-ui-plus/package.json:30-33](file://packages/adapters/view-ui-plus/package.json#L30-L33)
- [packages/adapters/element-plus/package.json:30-33](file://packages/adapters/element-plus/package.json#L30-L33)
- [packages/compat/package.json:24-25](file://packages/compat/package.json#L24-L25)

### 实际配置示例与最佳实践
- 安装与构建：使用 pnpm install 安装依赖，pnpm build 触发 Turborepo 全量构建；针对特定包使用 pnpm build:core、pnpm build:adapter:view、pnpm build:adapter:element。
- 开发模式：pnpm dev 启动 Turborepo 开发任务，结合持久化与缓存禁用策略提升调试效率。
- 发布策略：各包独立版本与发布，核心包与适配器保持语义化版本一致，兼容包跟随主版本同步。

章节来源
- [package.json:8-18](file://package.json#L8-L18)
- [MIGRATION.md:119-139](file://MIGRATION.md#L119-L139)