# 构建与部署

<cite>
**Referenced Files in This Document**   
- [vite.config.ts](file://vite.config.ts)
- [uno.config.ts](file://uno.config.ts)
- [package.json](file://package.json)
- [README.md](file://README.md)
</cite>

## 目录
1. [构建流程概述](#构建流程概述)
2. [开发构建与生产构建的区别](#开发构建与生产构建的区别)
3. [Vite 配置解析](#vite-配置解析)
4. [UnoCSS 自定义配置](#unocss-自定义配置)
5. [构建脚本执行机制](#构建脚本执行机制)
6. [静态资源输出结构](#静态资源输出结构)
7. [部署最佳实践](#部署最佳实践)

## 构建流程概述

本项目基于 Vite 构建工具实现现代化前端工程化流程，结合 Vue 3 和 UnoCSS 原子化 CSS 框架。整体构建流程围绕 `vite` 命令展开，通过 `package.json` 中定义的脚本入口驱动不同环境下的构建行为。

构建系统支持开发模式热重载、类型检查、代码格式化及生产级优化打包。核心配置文件包括 `vite.config.ts`（构建主配置）、`uno.config.ts`（样式引擎配置）以及 `package.json`（脚本命令定义），三者协同完成从源码到可部署静态资源的转换过程。

**Section sources**
- [vite.config.ts](file://vite.config.ts#L1-L30)
- [package.json](file://package.json#L1-L43)
- [README.md](file://README.md#L1-L38)

## 开发构建与生产构建的区别

开发构建与生产构建在目标、性能优化和输出内容上存在显著差异：

| 特性 | 开发构建 | 生产构建 |
|------|----------|----------|
| **启动命令** | `pnpm dev` | `pnpm build` |
| **主要目的** | 快速启动、热更新 | 生成优化后的静态资源 |
| **代码压缩** | 否 | 是（Terser 或 SWC） |
| **Source Map** | 完整映射 | 可选或隐藏 |
| **环境变量** | `.env.development` | `.env.production` |
| **依赖预构建** | 动态处理 | 静态分析并缓存 |
| **HMR 支持** | 是 | 否 |

开发构建侧重于提升开发者体验，启用热模块替换（HMR）以实现实时反馈；而生产构建则专注于性能优化，对 JavaScript、CSS 进行压缩与 Tree Shaking，移除调试代码，并生成适合 CDN 分发的静态文件。

**Section sources**
- [package.json](file://package.json#L6-L14)
- [README.md](file://README.md#L30-L37)

## Vite 配置解析

`vite.config.ts` 是项目的构建核心配置文件，定义了插件集成、路径别名、编译选项等关键设置。

### 插件集成
配置中注册了多个 Vite 插件：
- `@vitejs/plugin-vue`：支持 Vue 单文件组件解析，配置了自定义元素忽略规则（`isCustomElement: tag => tag.endsWith('-element')`），避免将特定标签误解析为 Vue 组件。
- `@vitejs/plugin-vue-jsx`：启用 JSX/TSX 语法支持。
- `vite-plugin-vue-devtools`：集成 Vue DevTools 调试工具。
- `unocss/vite`：引入 UnoCSS 样式引擎，实现原子化 CSS 按需生成。

### 路径别名
通过 `resolve.alias` 配置 `@` 指向 `src` 目录，简化模块导入路径，提升代码可读性与维护性。

### 环境变量处理
Vite 原生支持 `.env` 文件加载，根据 `import.meta.env.MODE` 区分不同环境，并自动注入 `import.meta.env.VITE_*` 前缀的环境变量。

```mermaid
flowchart TD
A["启动 vite"] --> B{开发模式?}
B --> |是| C["加载 vite.config.ts"]
C --> D["应用插件: vue, vueJsx, devtools, unocss"]
D --> E["设置路径别名 @ → src/"]
E --> F["启动开发服务器 + HMR"]
B --> |否| G["执行 vite build"]
G --> H["编译 TS + 处理 SFC"]
H --> I["应用 UnoCSS 转换"]
I --> J["压缩 JS/CSS"]
J --> K["输出 dist/ 目录"]
```

**Diagram sources**
- [vite.config.ts](file://vite.config.ts#L1-L30)

**Section sources**
- [vite.config.ts](file://vite.config.ts#L1-L30)

## UnoCSS 自定义配置

`uno.config.ts` 文件用于定制 UnoCSS 的行为，当前配置启用了两个重要转换器：

- `transformerVariantGroup()`：允许使用括号语法进行变体分组，例如 `hover:(bg-red-500 text-white)`，提升类名书写效率。
- `transformerDirectives()`：支持在 CSS 中使用 `@apply` 指令复用原子类，以及 `@screen` 响应式控制。

该配置确保了在模板中可以灵活使用组合式类名，同时保持样式的可维护性和简洁性。

```mermaid
classDiagram
class UnoCSSConfig {
+transformers : Transformer[]
}
class TransformerVariantGroup {
+name : "variant-group"
+transform()
}
class TransformerDirectives {
+name : "directives"
+transform()
}
UnoCSSConfig --> TransformerVariantGroup : "包含"
UnoCSSConfig --> TransformerDirectives : "包含"
```

**Diagram sources**
- [uno.config.ts](file://uno.config.ts#L1-L10)

**Section sources**
- [uno.config.ts](file://uno.config.ts#L1-L10)

## 构建脚本执行机制

`package.json` 中的 `scripts` 字段定义了标准化的构建命令：

- `dev`：直接运行 `vite`，启动开发服务器。
- `build`：并行执行类型检查与构建任务，使用 `run-p` 实现并发控制。
- `build-only`：仅执行 `vite build`，生成生产资源。
- `type-check`：调用 `vue-tsc --build` 进行完整的 TypeScript 类型校验。
- `preview`：启动本地预览服务器，模拟生产环境。

这种设计实现了构建流程的解耦与并行化，提升了 CI/CD 流水线效率。

**Section sources**
- [package.json](file://package.json#L6-L14)

## 静态资源输出结构

生产构建完成后，Vite 将输出默认的 `dist/` 目录，其典型结构如下：

```
dist/
├── assets/              # 打包后的 JS、CSS 资源
│   ├── index.[hash].js
│   └── style.[hash].css
├── index.html           # 入口 HTML 文件
└── favicon.ico          # 可选图标
```

所有资源均经过哈希命名以支持长期缓存，HTML 文件自动注入正确的资源引用路径。

**Section sources**
- [vite.config.ts](file://vite.config.ts#L1-L30)

## 部署最佳实践

### 静态服务器部署
将 `dist/` 目录内容部署至 Nginx、Apache 或 Caddy 等静态服务器时，需确保：
- 正确设置 MIME 类型。
- 启用 Gzip/Brotli 压缩。
- 配置 SPA 路由回退（将所有非资源请求重定向至 `index.html`）。

示例 Nginx 配置片段：
```nginx
location / {
  try_files $uri $uri/ /index.html;
}
```

### CDN 部署建议
- 利用 CDN 的边缘缓存能力，设置合理的缓存策略（如 `max-age=31536000` 对带哈希的静态资源）。
- 启用 HTTPS 和 HTTP/2。
- 使用版本化目录（如 `/v1.0.0/`）便于灰度发布与回滚。

### 自动化部署
推荐结合 GitHub Actions、GitLab CI 或 Jenkins 实现自动化构建与部署流水线，包含以下阶段：
1. 依赖安装
2. 类型检查
3. 生产构建
4. 构建产物验证
5. 自动上传至对象存储或 CDN

**Section sources**
- [README.md](file://README.md#L30-L37)