# 构建工具集成

<cite>
**本文引用的文件**
- [vite.config.js](file://vite.config.js)
- [package.json](file://package.json)
- [turbo.json](file://turbo.json)
- [pnpm-workspace.yaml](file://pnpm-workspace.yaml)
- [ARCHITECTURE_SUMMARY.md](file://ARCHITECTURE_SUMMARY.md)
- [packages/core/vite.config.js](file://packages/core/vite.config.js)
- [packages/adapters/view-ui-plus/vite.config.js](file://packages/adapters/view-ui-plus/vite.config.js)
- [packages/adapters/element-plus/vite.config.js](file://packages/adapters/element-plus/vite.config.js)
- [packages/compat/vite.config.js](file://packages/compat/vite.config.js)
- [packages/core/package.json](file://packages/core/package.json)
- [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 的构建工具集成，重点覆盖以下方面：
- 与 Vite、Webpack、Rollup 的集成策略与最佳实践
- 库模式与应用模式构建、代码分割与 Tree Shaking 优化
- 多包（Monorepo）构建与缓存策略
- 构建配置示例与多环境参数配置
- 构建性能优化、产物分析与依赖处理

Pro-IVIEW V3 采用 Vite 作为主要构建工具，并结合 Turborepo 实现多包缓存加速；同时提供向后兼容包与 UI 适配器包，满足不同使用场景。

## 项目结构
项目采用 Monorepo 架构，使用 pnpm workspace 管理多包，Turborepo 提供跨包构建缓存与流水线控制。根级 Vite 配置用于库模式构建与文档站点构建；各子包拥有独立的 Vite 配置以适配各自的构建目标。

```mermaid
graph TB
subgraph "根目录"
RootPkg["根 package.json"]
RootVite["根 vite.config.js"]
Turbo["turbo.json"]
WS["pnpm-workspace.yaml"]
end
subgraph "packages/core"
CorePkg["core/package.json"]
CoreVite["core/vite.config.js"]
end
subgraph "packages/adapters"
ViewVite["adapters/view-ui-plus/vite.config.js"]
ElementVite["adapters/element-plus/vite.config.js"]
end
subgraph "packages/compat"
CompatVite["compat/vite.config.js"]
end
RootPkg --> RootVite
RootVite --> CoreVite
RootVite --> ViewVite
RootVite --> ElementVite
RootVite --> CompatVite
WS --> CorePkg
WS --> ViewVite
WS --> ElementVite
WS --> CompatVite
Turbo --> RootVite
```

图表来源
- [vite.config.js:1-100](file://vite.config.js#L1-L100)
- [turbo.json:1-18](file://turbo.json#L1-L18)
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [packages/core/vite.config.js:1-31](file://packages/core/vite.config.js#L1-L31)
- [packages/adapters/view-ui-plus/vite.config.js:1-25](file://packages/adapters/view-ui-plus/vite.config.js#L1-L25)
- [packages/adapters/element-plus/vite.config.js:1-25](file://packages/adapters/element-plus/vite.config.js#L1-L25)
- [packages/compat/vite.config.js:1-25](file://packages/compat/vite.config.js#L1-L25)

章节来源
- [ARCHITECTURE_SUMMARY.md:59-120](file://ARCHITECTURE_SUMMARY.md#L59-L120)
- [pnpm-workspace.yaml:1-5](file://pnpm-workspace.yaml#L1-L5)
- [turbo.json:1-18](file://turbo.json#L1-L18)

## 核心组件
- 根级 Vite 配置：提供库模式构建、UMD/ES 输出、外部化依赖、压缩与拷贝插件、代理与环境变量加载。
- 子包 Vite 配置：分别针对 core、view-ui-plus 适配器、element-plus 适配器、compat 向后兼容包进行定制化构建。
- 包管理与导出：各包通过 exports 字段声明 ESM 与 CJS 导出，配合 peerDependencies 管理外部依赖。
- Monorepo 与缓存：pnpm workspace + Turborepo，提升多包构建效率与一致性。

章节来源
- [vite.config.js:11-99](file://vite.config.js#L11-L99)
- [packages/core/vite.config.js:7-30](file://packages/core/vite.config.js#L7-L30)
- [packages/adapters/view-ui-plus/vite.config.js:5-24](file://packages/adapters/view-ui-plus/vite.config.js#L5-L24)
- [packages/adapters/element-plus/vite.config.js:5-24](file://packages/adapters/element-plus/vite.config.js#L5-L24)
- [packages/compat/vite.config.js:5-24](file://packages/compat/vite.config.js#L5-L24)
- [packages/core/package.json:8-14](file://packages/core/package.json#L8-L14)
- [packages/adapters/view-ui-plus/package.json:8-14](file://packages/adapters/view-ui-plus/package.json#L8-L14)
- [packages/adapters/element-plus/package.json:8-14](file://packages/adapters/element-plus/package.json#L8-L14)
- [packages/compat/package.json:8-14](file://packages/compat/package.json#L8-L14)

## 架构总览
下图展示了从根 Vite 配置到各子包构建的整体流程，以及外部依赖的处理策略。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant RootVite as "根 vite.config.js"
participant CoreVite as "core/vite.config.js"
participant AdapterView as "adapters/view-ui-plus/vite.config.js"
participant AdapterElement as "adapters/element-plus/vite.config.js"
participant CompatVite as "compat/vite.config.js"
Dev->>RootVite : 触发构建命令
RootVite->>RootVite : 加载环境变量/模式
RootVite->>CoreVite : 构建核心包
RootVite->>AdapterView : 构建 view-ui-plus 适配器
RootVite->>AdapterElement : 构建 element-plus 适配器
RootVite->>CompatVite : 构建向后兼容包
RootVite-->>Dev : 产出 lib 目录与产物
```

图表来源
- [vite.config.js:11-99](file://vite.config.js#L11-L99)
- [packages/core/vite.config.js:7-30](file://packages/core/vite.config.js#L7-L30)
- [packages/adapters/view-ui-plus/vite.config.js:5-24](file://packages/adapters/view-ui-plus/vite.config.js#L5-L24)
- [packages/adapters/element-plus/vite.config.js:5-24](file://packages/adapters/element-plus/vite.config.js#L5-L24)
- [packages/compat/vite.config.js:5-24](file://packages/compat/vite.config.js#L5-L24)

## 详细组件分析

### 根 Vite 配置（库模式与多环境）
- 库模式构建：entry 指向 packages/index.js，输出 UMD/ES 名称为 pro_iview，产物目录由环境变量控制。
- 外部化策略：对 vue、axios、lodash-es、dayjs、view-ui-plus、async-validator、qs、default-passive-events、vue3-click-away、vuedraggable、vue-i18n、mousetrap 等进行外部化，避免将这些依赖打包进库。
- UMD 全局映射：为外部依赖提供全局变量名，便于浏览器直接引入。
- 压缩与清理：启用 Terser 去除 console 与 debugger。
- 拷贝资源：构建时将语言包拷贝至 lib/locales。
- 开发服务器：配置代理，便于本地联调。

```mermaid
flowchart TD
Start(["开始: 根 Vite 配置"]) --> LoadEnv["加载环境变量/模式"]
LoadEnv --> LibBuild["进入库模式构建<br/>设置 entry/name/formats"]
LibBuild --> External["配置外部化依赖列表"]
External --> Globals["配置 UMD 全局映射"]
Globals --> Plugins["配置 Rollup 插件<br/>压缩/拷贝"]
Plugins --> Output["输出产物(lib 目录)"]
Output --> End(["结束"])
```

图表来源
- [vite.config.js:11-99](file://vite.config.js#L11-L99)

章节来源
- [vite.config.js:11-99](file://vite.config.js#L11-L99)

### 子包 Vite 配置（按需定制）
- core 包：支持 ES 与 UMD 双格式，外部化 vue，提供别名 @ 指向 src。
- view-ui-plus 适配器：输出 ES 与 UMD，外部化 vue 与 view-ui-plus。
- element-plus 适配器：输出 ES 与 UMD，外部化 vue 与 element-plus。
- compat 向后兼容包：输出 ES 与 UMD，外部化 vue 与 view-ui-plus。

```mermaid
classDiagram
class RootVite {
+库模式构建
+外部化依赖
+压缩与拷贝
+环境变量加载
}
class CoreVite {
+ES/UMD 双格式
+外部化 vue
+路径别名
}
class ViewAdapterVite {
+ES/UMD 双格式
+外部化 vue/view-ui-plus
}
class ElementAdapterVite {
+ES/UMD 双格式
+外部化 vue/element-plus
}
class CompatVite {
+ES/UMD 双格式
+外部化 vue/view-ui-plus
}
RootVite --> CoreVite : "构建核心包"
RootVite --> ViewAdapterVite : "构建适配器"
RootVite --> ElementAdapterVite : "构建适配器"
RootVite --> CompatVite : "构建兼容包"
```

图表来源
- [packages/core/vite.config.js:7-30](file://packages/core/vite.config.js#L7-L30)
- [packages/adapters/view-ui-plus/vite.config.js:5-24](file://packages/adapters/view-ui-plus/vite.config.js#L5-L24)
- [packages/adapters/element-plus/vite.config.js:5-24](file://packages/adapters/element-plus/vite.config.js#L5-L24)
- [packages/compat/vite.config.js:5-24](file://packages/compat/vite.config.js#L5-L24)

章节来源
- [packages/core/vite.config.js:7-30](file://packages/core/vite.config.js#L7-L30)
- [packages/adapters/view-ui-plus/vite.config.js:5-24](file://packages/adapters/view-ui-plus/vite.config.js#L5-L24)
- [packages/adapters/element-plus/vite.config.js:5-24](file://packages/adapters/element-plus/vite.config.js#L5-L24)
- [packages/compat/vite.config.js:5-24](file://packages/compat/vite.config.js#L5-L24)

### 包导出与依赖管理
- 导出字段：各包通过 exports 字段声明 import/require/types，确保 ESM 与 CommonJS 场景一致。
- 文件清单：files 字段限定发布目录，避免多余文件进入 npm 包。
- peerDependencies：核心包与适配器声明对 vue 的 peer 依赖，减少重复打包与版本冲突风险。
- 依赖范围：核心包声明较多运行时依赖，适配器仅声明 vue，compat 依赖 core 与适配器。

```mermaid
erDiagram
CORE_PKG {
string name
string main
string module
string typings
}
VIEW_PKG {
string name
string main
string module
string typings
}
ELEMENT_PKG {
string name
string main
string module
string typings
}
COMPAT_PKG {
string name
string main
string module
string typings
}
CORE_PKG ||--o{ VIEW_PKG : "被适配器依赖"
CORE_PKG ||--o{ ELEMENT_PKG : "被适配器依赖"
CORE_PKG ||--o{ COMPAT_PKG : "被兼容包依赖"
```

图表来源
- [packages/core/package.json:8-14](file://packages/core/package.json#L8-L14)
- [packages/adapters/view-ui-plus/package.json:8-14](file://packages/adapters/view-ui-plus/package.json#L8-L14)
- [packages/adapters/element-plus/package.json:8-14](file://packages/adapters/element-plus/package.json#L8-L14)
- [packages/compat/package.json:8-14](file://packages/compat/package.json#L8-L14)

章节来源
- [packages/core/package.json:8-14](file://packages/core/package.json#L8-L14)
- [packages/adapters/view-ui-plus/package.json:8-14](file://packages/adapters/view-ui-plus/package.json#L8-L14)
- [packages/adapters/element-plus/package.json:8-14](file://packages/adapters/element-plus/package.json#L8-L14)
- [packages/compat/package.json:8-14](file://packages/compat/package.json#L8-L14)

### 多环境与脚本
- 环境变量：根 Vite 配置通过 loadEnv 从 env 目录加载变量，支持 docs/aopule 等模式。
- 脚本命令：根 package.json 提供 dev/build/lib/build:core/build:adapter 等脚本，结合 Turborepo 并行构建。
- 文档构建：build:docs 与 build:aopule 分别对应不同模式的构建。

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

## 依赖分析
- 外部化依赖：根 Vite 对大量第三方库进行外部化，结合 UMD 全局映射，适合浏览器直引或与打包器协作。
- Monorepo 依赖：各包通过 workspace:* 引用彼此，避免重复安装与版本漂移。
- 缓存与流水线：Turborepo 通过 pipeline 定义构建顺序与输出缓存，提升整体构建速度。

```mermaid
graph LR
RootVite["根 vite.config.js"] --> |外部化| Vue["vue"]
RootVite --> Axios["axios"]
RootVite --> Lodash["lodash-es"]
RootVite --> Dayjs["dayjs"]
RootVite --> VIUp["view-ui-plus"]
RootVite --> AV["async-validator"]
RootVite --> QS["qs"]
RootVite --> DPE["default-passive-events"]
RootVite --> VCA["vue3-click-away"]
RootVite --> VD["vuedraggable"]
RootVite --> I18n["vue-i18n"]
RootVite --> Mousetrap["mousetrap"]
CorePkg["core/package.json"] --> Vue
ViewPkg["view-ui-plus/package.json"] --> Vue
ViewPkg --> VIUp
ElementPkg["element-plus/package.json"] --> Vue
ElementPkg --> EP["element-plus"]
CompatPkg["compat/package.json"] --> CorePkg
CompatPkg --> ViewPkg
```

图表来源
- [vite.config.js:27-58](file://vite.config.js#L27-L58)
- [packages/core/package.json:23-35](file://packages/core/package.json#L23-L35)
- [packages/adapters/view-ui-plus/package.json:23-33](file://packages/adapters/view-ui-plus/package.json#L23-L33)
- [packages/adapters/element-plus/package.json:23-33](file://packages/adapters/element-plus/package.json#L23-L33)
- [packages/compat/package.json:23-28](file://packages/compat/package.json#L23-L28)

章节来源
- [vite.config.js:27-70](file://vite.config.js#L27-L70)
- [packages/core/package.json:23-45](file://packages/core/package.json#L23-L45)
- [packages/adapters/view-ui-plus/package.json:23-33](file://packages/adapters/view-ui-plus/package.json#L23-L33)
- [packages/adapters/element-plus/package.json:23-33](file://packages/adapters/element-plus/package.json#L23-L33)
- [packages/compat/package.json:23-28](file://packages/compat/package.json#L23-L28)

## 性能考虑
- 外部化与 Tree Shaking：通过 external 将大型依赖交由使用者或打包器处理，结合 ESM 导出利于 Tree Shaking。
- 产物拆分：库模式可输出 ES 与 UMD，应用侧可按需选择模块格式，减少冗余代码。
- 压缩与去冗：启用 Terser 去除 console 与 debugger，降低体积。
- 并行与缓存：Turborepo 并行执行构建任务，利用缓存避免重复编译。
- 依赖精简：将非核心依赖设为 peerDependencies，减少嵌套 node_modules 与重复打包。

## 故障排查指南
- 构建失败（外部化未生效）：确认 external 列表是否包含目标依赖，且 UMD globals 映射正确。
- 语言包缺失：检查 copy 插件的目标路径与产物目录是否匹配。
- 环境变量未生效：确认 envDir 设置与 env 目录结构，以及 loadEnv 的 mode 参数。
- 依赖冲突：核对 peerDependencies 与实际安装的版本，避免多版本共存。
- 文档构建异常：检查 build:docs 与 build:aopule 对应的模式与外部化配置差异。

章节来源
- [vite.config.js:14-16](file://vite.config.js#L14-L16)
- [vite.config.js:80-86](file://vite.config.js#L80-L86)
- [vite.config.js:11-15](file://vite.config.js#L11-L15)

## 结论
Pro-IVIEW V3 的构建体系以 Vite 为核心，结合 Monorepo 与 Turborepo，实现了高可维护性与高性能的多包构建。通过合理的外部化策略、ESM/UMD 双格式输出与压缩优化，既能满足库模式的灵活接入，也能支撑应用模式的高效开发。建议在实际项目中根据使用场景选择合适的构建模式与依赖管理策略，并持续利用缓存与并行能力提升构建效率。

## 附录
- 构建命令参考
  - 开发：根脚本 dev
  - 全量构建：根脚本 build
  - 单包构建：build:core、build:adapter:view、build:adapter:element
  - 文档构建：build:docs、build:aopule
- 多环境参数
  - 通过 --mode 传入 docs/aopule 等模式，根 Vite 配置会加载对应 env 下的变量
- 产物位置
  - 根 Vite 配置通过环境变量控制 outDir，默认输出至 lib 目录
- 依赖处理建议
  - 将常用第三方库设为 external，结合 UMD globals 映射
  - 对于核心逻辑，优先使用 ESM 导出以增强 Tree Shaking
  - 使用 peerDependencies 管理对 vue 等框架的依赖

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