6.7 KiB
构建与部署
**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)目录
构建流程概述
本项目基于 Vite 构建工具实现现代化前端工程化流程，结合 Vue 3 和 UnoCSS 原子化 CSS 框架。整体构建流程围绕 vite 命令展开，通过 package.json 中定义的脚本入口驱动不同环境下的构建行为。
构建系统支持开发模式热重载、类型检查、代码格式化及生产级优化打包。核心配置文件包括 vite.config.ts（构建主配置）、uno.config.ts（样式引擎配置）以及 package.json（脚本命令定义），三者协同完成从源码到可部署静态资源的转换过程。
Section sources
开发构建与生产构建的区别
开发构建与生产构建在目标、性能优化和输出内容上存在显著差异：
| 特性 | 开发构建 | 生产构建 |
|---|---|---|
| 启动命令 | pnpm dev |
pnpm build |
| 主要目的 | 快速启动、热更新 | 生成优化后的静态资源 |
| 代码压缩 | 否 | 是（Terser 或 SWC） |
| Source Map | 完整映射 | 可选或隐藏 |
| 环境变量 | .env.development |
.env.production |
| 依赖预构建 | 动态处理 | 静态分析并缓存 |
| HMR 支持 | 是 | 否 |
开发构建侧重于提升开发者体验，启用热模块替换（HMR）以实现实时反馈；而生产构建则专注于性能优化，对 JavaScript、CSS 进行压缩与 Tree Shaking，移除调试代码，并生成适合 CDN 分发的静态文件。
Section sources
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_* 前缀的环境变量。
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
Section sources
UnoCSS 自定义配置
uno.config.ts 文件用于定制 UnoCSS 的行为，当前配置启用了两个重要转换器：
transformerVariantGroup()：允许使用括号语法进行变体分组，例如hover:(bg-red-500 text-white)，提升类名书写效率。transformerDirectives()：支持在 CSS 中使用@apply指令复用原子类，以及@screen响应式控制。
该配置确保了在模板中可以灵活使用组合式类名，同时保持样式的可维护性和简洁性。
classDiagram
class UnoCSSConfig {
+transformers : Transformer[]
}
class TransformerVariantGroup {
+name : "variant-group"
+transform()
}
class TransformerDirectives {
+name : "directives"
+transform()
}
UnoCSSConfig --> TransformerVariantGroup : "包含"
UnoCSSConfig --> TransformerDirectives : "包含"
Diagram sources
Section sources
构建脚本执行机制
package.json 中的 scripts 字段定义了标准化的构建命令：
dev：直接运行vite，启动开发服务器。build：并行执行类型检查与构建任务，使用run-p实现并发控制。build-only：仅执行vite build，生成生产资源。type-check：调用vue-tsc --build进行完整的 TypeScript 类型校验。preview：启动本地预览服务器，模拟生产环境。
这种设计实现了构建流程的解耦与并行化，提升了 CI/CD 流水线效率。
Section sources
静态资源输出结构
生产构建完成后，Vite 将输出默认的 dist/ 目录，其典型结构如下：
dist/
├── assets/ # 打包后的 JS、CSS 资源
│ ├── index.[hash].js
│ └── style.[hash].css
├── index.html # 入口 HTML 文件
└── favicon.ico # 可选图标
所有资源均经过哈希命名以支持长期缓存，HTML 文件自动注入正确的资源引用路径。
Section sources
部署最佳实践
静态服务器部署
将 dist/ 目录内容部署至 Nginx、Apache 或 Caddy 等静态服务器时，需确保：
- 正确设置 MIME 类型。
- 启用 Gzip/Brotli 压缩。
- 配置 SPA 路由回退（将所有非资源请求重定向至
index.html）。
示例 Nginx 配置片段：
location / {
try_files $uri $uri/ /index.html;
}
CDN 部署建议
- 利用 CDN 的边缘缓存能力，设置合理的缓存策略（如
max-age=31536000对带哈希的静态资源）。 - 启用 HTTPS 和 HTTP/2。
- 使用版本化目录（如
/v1.0.0/）便于灰度发布与回滚。
自动化部署
推荐结合 GitHub Actions、GitLab CI 或 Jenkins 实现自动化构建与部署流水线，包含以下阶段：
- 依赖安装
- 类型检查
- 生产构建
- 构建产物验证
- 自动上传至对象存储或 CDN
Section sources