# 构建与部署

<cite>
**本文引用的文件**
- [vite.config.js](file://frontend/vite.config.js)
- [package.json](file://frontend/package.json)
- [DEBUG_GUIDE.md](file://frontend/DEBUG_GUIDE.md)
- [frontend.md](file://docs/frontend.md)
- [main.js](file://frontend/src/main.js)
- [router/index.js](file://frontend/src/router/index.js)
- [api/request.js](file://frontend/src/api/request.js)
- [stores/user.js](file://frontend/src/stores/user.js)
- [assets/main.scss](file://frontend/src/assets/main.scss)
- [test-api.html](file://frontend/public/test-api.html)
- [test-api.html](file://frontend/dist/test-api.html)
- [test_frontend_connection.py](file://test_frontend_connection.py)
</cite>

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

## 简介
本指南面向前端构建与部署，围绕 Vite 构建配置、环境变量、资源优化、静态资源与代码分割、打包分析、生产构建与 CDN 缓存策略、容器化与 Nginx 反向代理、自动化部署与 CI/CD、版本发布管理、性能监控与错误追踪、用户体验优化以及调试与性能分析方法进行系统化说明。文档同时结合仓库现有前端工程与配套文档，确保内容可落地、可验证。

## 项目结构
前端工程采用 Vite + Vue 3 + Pinia + Element Plus 的现代前端技术栈，源码位于 frontend 目录，构建产物输出至 dist 目录；开发时通过 Vite Dev Server 提供本地服务与代理能力；路由、状态管理、HTTP 客户端等关键模块均在 src 目录下组织。

```mermaid
graph TB
subgraph "前端工程(frontend)"
SRC["src 源码<br/>main.js/router/api/stores/assets"]
DIST["dist 构建产物"]
VCFG["vite.config.js"]
PKG["package.json"]
PUB["public 静态资源"]
end
SRC --> VCFG
SRC --> PKG
VCFG --> DIST
PKG --> DIST
PUB --> DIST
```

图表来源
- [vite.config.js](file://frontend/vite.config.js#L1-L22)
- [package.json](file://frontend/package.json#L1-L27)

章节来源
- [vite.config.js](file://frontend/vite.config.js#L1-L22)
- [package.json](file://frontend/package.json#L1-L27)
- [frontend.md](file://docs/frontend.md#L1-L416)

## 核心组件
- 构建与开发服务器
  - Vite 插件与别名配置、开发服务器端口与代理规则
  - 开发脚本、构建脚本与预览脚本
- 应用入口与全局依赖
  - 应用挂载、插件注册、国际化与全局样式引入
- 路由与导航
  - 基于 History 模式的路由配置与前置守卫
- 状态管理
  - Pinia Store 的用户状态与登录流程
- HTTP 客户端
  - Axios 实例、基础地址、超时、请求/响应拦截器与错误处理
- 样式与主题
  - 全局 SCSS 变量、布局与组件样式规范
- 调试与测试工具
  - 内置 API 测试页面与前端连通性测试脚本

章节来源
- [vite.config.js](file://frontend/vite.config.js#L1-L22)
- [package.json](file://frontend/package.json#L1-L27)
- [main.js](file://frontend/src/main.js#L1-L24)
- [router/index.js](file://frontend/src/router/index.js#L1-L116)
- [stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [api/request.js](file://frontend/src/api/request.js#L1-L66)
- [assets/main.scss](file://frontend/src/assets/main.scss#L1-L186)
- [DEBUG_GUIDE.md](file://frontend/DEBUG_GUIDE.md#L1-L119)
- [frontend.md](file://docs/frontend.md#L1-L416)

## 架构总览
前端应用通过 Vite 构建，开发时由 Vite Dev Server 提供本地服务与代理，生产时生成静态资源并由 Nginx 提供静态文件服务与反向代理。HTTP 请求通过 Axios 发送，统一拦截处理错误与鉴权逻辑；路由守卫保障登录态校验；Pinia 管理用户状态。

```mermaid
graph TB
Browser["浏览器客户端"] --> ViteDev["Vite 开发服务器<br/>端口:5173"]
ViteDev --> Proxy["代理规则<br/>/api -> 后端"]
Browser --> BuildOut["构建产物 dist/*"]
BuildOut --> Nginx["Nginx 反向代理"]
Nginx --> Backend["后端服务"]
subgraph "前端应用"
Axios["Axios 实例<br/>拦截器/错误处理"]
Router["Vue Router<br/>前置守卫"]
Stores["Pinia Store<br/>用户状态"]
end
Browser --> Axios
Browser --> Router
Browser --> Stores
Axios --> Proxy
Proxy --> Backend
```

图表来源
- [vite.config.js](file://frontend/vite.config.js#L12-L20)
- [api/request.js](file://frontend/src/api/request.js#L5-L12)
- [router/index.js](file://frontend/src/router/index.js#L103-L113)
- [stores/user.js](file://frontend/src/stores/user.js#L6-L48)

## 详细组件分析

### Vite 构建与开发服务器
- 插件与别名
  - 使用 Vue 插件与路径别名 @ 指向 src，便于导入
- 开发服务器
  - 端口 5173，默认启用
  - 代理 /api 到后端地址，解决开发跨域问题
- 构建与脚本
  - 提供 dev/build/preview 三个常用脚本，满足开发、构建与本地预览

```mermaid
flowchart TD
Start(["启动 Vite"]) --> LoadCfg["加载 vite.config.js"]
LoadCfg --> Plugins["初始化插件与别名"]
Plugins --> DevServer["启动开发服务器<br/>端口:5173"]
DevServer --> ProxyRule["配置 /api 代理"]
ProxyRule --> Ready(["开发就绪"])
```

图表来源
- [vite.config.js](file://frontend/vite.config.js#L5-L21)

章节来源
- [vite.config.js](file://frontend/vite.config.js#L1-L22)
- [package.json](file://frontend/package.json#L6-L10)

### 应用入口与全局依赖
- 应用挂载与插件
  - 注册 Pinia、Vue Router、Element Plus 并设置中文语言包
  - 注册 Element Plus 图标组件
- 全局样式
  - 引入全局 SCSS，包含主题变量、布局与组件样式

```mermaid
sequenceDiagram
participant Entry as "main.js"
participant App as "Vue 应用"
participant Router as "Vue Router"
participant Pinia as "Pinia"
participant EP as "Element Plus"
Entry->>App : createApp(App)
Entry->>Pinia : app.use(createPinia())
Entry->>Router : app.use(router)
Entry->>EP : app.use(ElementPlus, { locale })
Entry->>App : mount("#app")
```

图表来源
- [main.js](file://frontend/src/main.js#L12-L23)

章节来源
- [main.js](file://frontend/src/main.js#L1-L24)
- [assets/main.scss](file://frontend/src/assets/main.scss#L1-L186)

### 路由与导航
- 路由配置
  - 基于 History 模式，定义多级路由与懒加载页面
- 前置守卫
  - 未登录访问受保护路由时重定向至登录页
  - 动态设置页面标题

```mermaid
flowchart TD
Enter["进入路由"] --> Guard["前置守卫"]
Guard --> HasToken{"是否存在 token?"}
HasToken --> |是| Allow["放行"]
HasToken --> |否| ToLogin["重定向 /login"]
Allow --> Render["渲染目标页面"]
ToLogin --> End(["结束"])
Render --> End
```

图表来源
- [router/index.js](file://frontend/src/router/index.js#L103-L113)

章节来源
- [router/index.js](file://frontend/src/router/index.js#L1-L116)

### 状态管理（用户）
- 用户状态
  - 存储 token 与用户信息，提供登录、获取用户信息、登出方法
  - 登出时清除 token 并跳转登录页

```mermaid
classDiagram
class UserStore {
+string token
+object userInfo
+login(username, password) Promise~boolean~
+getUserInfo() Promise~object|null~
+logout() void
}
class AuthAPI {
+login(data) Promise
+getCurrentUser() Promise
}
UserStore --> AuthAPI : "调用"
```

图表来源
- [stores/user.js](file://frontend/src/stores/user.js#L6-L48)
- [api/request.js](file://frontend/src/api/request.js#L1-L66)

章节来源
- [stores/user.js](file://frontend/src/stores/user.js#L1-L49)

### HTTP 客户端与错误处理
- Axios 实例
  - 基础地址指向 /api/v1，统一超时与 Content-Type
- 请求拦截器
  - 自动附加 Bearer Token
- 响应拦截器
  - 统一错误提示与 401 跳转登录
  - 对不同状态码给出明确提示

```mermaid
sequenceDiagram
participant Comp as "组件"
participant Store as "Pinia Store"
participant API as "API 函数"
participant Axios as "Axios 实例"
participant Inter as "拦截器"
participant BE as "后端"
Comp->>Store : 触发业务动作
Store->>API : 调用 API 函数
API->>Axios : 发起请求
Axios->>Inter : 请求拦截器注入 Authorization
Inter->>BE : 发送请求
BE-->>Inter : 返回响应
Inter-->>Axios : 响应拦截器处理
Axios-->>API : 返回数据/抛错
API-->>Store : 更新状态/提示
Store-->>Comp : 视图更新
```

图表来源
- [api/request.js](file://frontend/src/api/request.js#L5-L66)

章节来源
- [api/request.js](file://frontend/src/api/request.js#L1-L66)

### 样式与主题
- 全局变量与主题色
  - 定义主色、状态色、文本色、边框色与背景色
- 布局与组件样式
  - 侧边栏、头部、主区域、表格、卡片、状态标签、分数等级、图表容器等样式规范

章节来源
- [assets/main.scss](file://frontend/src/assets/main.scss#L1-L186)

### 调试与测试工具
- 内置 API 测试页面
  - 提供健康检查与登录测试，便于快速验证前后端连通性
- 前端连通性测试脚本
  - 检查 CORS 配置、登录接口可用性与返回值

章节来源
- [DEBUG_GUIDE.md](file://frontend/DEBUG_GUIDE.md#L1-L119)
- [test-api.html](file://frontend/public/test-api.html#L39-L75)
- [test_frontend_connection.py](file://test_frontend_connection.py#L38-L74)

## 依赖关系分析
- 组件耦合
  - main.js 作为入口，集中注册插件与依赖
  - router/index.js 与 stores/user.js 彼此独立，通过业务调用交互
  - api/request.js 作为 HTTP 客户端被各 API 模块复用
- 外部依赖
  - Vue 3、Vue Router、Pinia、Axios、Element Plus、ECharts、Day.js、Vite、Sass

```mermaid
graph LR
Main["main.js"] --> Router["router/index.js"]
Main --> Pinia["stores/*"]
Main --> EP["Element Plus"]
Router --> Views["views/*"]
Pinia --> API["api/*"]
API --> Request["api/request.js"]
Request --> Axios["axios"]
```

图表来源
- [main.js](file://frontend/src/main.js#L1-L24)
- [router/index.js](file://frontend/src/router/index.js#L1-L116)
- [stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [api/request.js](file://frontend/src/api/request.js#L1-L66)

章节来源
- [package.json](file://frontend/package.json#L11-L25)

## 性能考量
- 构建与资源优化
  - 使用 Vite 的原生按需加载与 Tree Shaking，减少初始包体
  - 将第三方 UI 组件与图表库按需引入，避免全量打包
- 代码分割
  - 路由级懒加载与组件级拆分，配合 Vite 的动态导入实现自然分割
- 打包分析
  - 建议使用 Vite 插件进行体积分析，定位大体积依赖与重复模块
- 生产构建
  - 使用构建脚本生成 dist，开启压缩与哈希命名，便于缓存与回滚
- CDN 与缓存
  - 将静态资源托管至 CDN，设置长缓存与版本化文件名；对 HTML 设置短缓存
- 运行时性能
  - 合理使用虚拟滚动、防抖与节流；对图表与大数据表格进行分页与懒加载

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 常见问题与解决
  - CORS 错误：属预期行为，检查后端 CORS 配置
  - 404：检查 Vite 代理配置与后端路由
  - 500：检查后端日志与数据库状态
  - Network Error：确认后端服务已启动
- 调试步骤
  - 打开浏览器开发者工具，查看 Console 与 Network
  - 使用内置 API 测试页面与连通性脚本快速定位问题
  - 清除浏览器缓存与 localStorage，执行硬刷新
  - 重启后端与前端开发服务器

章节来源
- [DEBUG_GUIDE.md](file://frontend/DEBUG_GUIDE.md#L10-L95)
- [test_frontend_connection.py](file://test_frontend_connection.py#L38-L74)

## 结论
本指南基于仓库现有前端工程与文档，系统梳理了 Vite 构建配置、开发代理、HTTP 客户端、路由与状态管理、样式体系与调试工具，并给出了生产构建、CDN 与缓存、容器化与 Nginx 反向代理、自动化部署与版本管理、性能监控与错误追踪、用户体验优化与调试分析的实践建议。建议在实际部署中结合团队规范与基础设施，逐步完善 CI/CD 与监控体系，持续优化构建与运行时性能。

[本节为总结性内容，不直接分析具体文件]

## 附录

### A. Vite 构建与环境变量
- 构建脚本
  - 开发：npm run dev
  - 构建：npm run build
  - 预览：npm run preview
- 环境变量
  - 建议通过 .env 文件管理 API 基础地址、CDN 基础路径等，避免硬编码
  - 在 Vite 中可通过 import.meta.env 访问

章节来源
- [package.json](file://frontend/package.json#L6-L10)
- [frontend.md](file://docs/frontend.md#L380-L394)

### B. 静态资源处理、代码分割与打包分析
- 静态资源
  - public 目录用于放置无需打包的静态资源；构建后与 dist 对齐
- 代码分割
  - 路由懒加载与组件拆分天然实现分割；可结合 Vite 插件进行可视化分析
- 打包分析
  - 推荐使用 @rollup/plugin-visualizer 或 vite-bundle-analyzer

章节来源
- [frontend.md](file://docs/frontend.md#L17-L48)
- [router/index.js](file://frontend/src/router/index.js#L1-L116)

### C. 生产构建、CDN 与缓存策略
- 生产构建
  - 使用 npm run build 生成 dist；确保代理与基础路径在生产环境关闭或适配
- CDN 与缓存
  - 将 dist 下静态资源上传至 CDN；HTML 设置短缓存；JS/CSS 设置长缓存并带内容指纹
- 反向代理
  - Nginx 将静态资源交由 Nginx 直接提供，/api 前缀转发至后端

[本节为通用指导，不直接分析具体文件]

### D. Docker 容器化与 Nginx 反向代理
- 容器化
  - 使用 Nginx 镜像作为静态资源服务器，挂载 dist 目录
- Nginx 配置要点
  - 静态文件根目录指向 dist
  - /api 前缀代理至后端服务
  - 设置缓存与 Gzip 压缩
- 反向代理
  - 将前端域名解析到 Nginx，Nginx 负责静态资源与 API 转发

[本节为通用指导，不直接分析具体文件]

### E. 自动化部署、CI/CD 与版本发布
- CI/CD
  - 在流水线中执行安装依赖、构建、测试与部署步骤
  - 构建产物上传至制品库或直接部署到 Nginx
- 版本发布
  - 使用语义化版本管理；构建产物与版本关联，便于回滚

[本节为通用指导，不直接分析具体文件]

### F. 性能监控、错误追踪与用户体验优化
- 性能监控
  - 关注首屏时间、交互延迟与内存占用；结合浏览器性能面板与 Lighthouse
- 错误追踪
  - 前端错误上报与后端错误日志联动；统一错误提示与用户引导
- 用户体验
  - 加载骨架屏、空态与错误态；合理分页与搜索；移动端适配

[本节为通用指导，不直接分析具体文件]

### G. 调试工具使用与性能分析
- 调试工具
  - 浏览器开发者工具、Vue DevTools、网络面板、性能面板
- 性能分析
  - 关注资源加载顺序、缓存命中率与关键渲染路径

章节来源
- [DEBUG_GUIDE.md](file://frontend/DEBUG_GUIDE.md#L1-L119)