182 lines
6.7 KiB
Markdown
182 lines
6.7 KiB
Markdown
# 构建与部署
|
||
|
||
<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) |