提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/前端开发指南/构建与部署.md
+++ b/.qoder/repowiki/zh/content/前端开发指南/构建与部署.md
@@ -0,0 +1,421 @@
+# 构建与部署
+
+<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)