hospital_performance/.qoder/repowiki/zh/content/前端开发指南/构建与部署.md

构建与部署

**本文引用的文件** - [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)

目录

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 目录下组织。

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
• package.json

章节来源

• vite.config.js
• package.json
• frontend.md

核心组件

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

章节来源

• vite.config.js
• package.json
• main.js
• router/index.js
• stores/user.js
• api/request.js
• assets/main.scss
• DEBUG_GUIDE.md
• frontend.md

架构总览

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

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
• api/request.js
• router/index.js
• stores/user.js

详细组件分析

Vite 构建与开发服务器

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

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

图表来源

• vite.config.js

章节来源

• vite.config.js
• package.json

应用入口与全局依赖

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

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

章节来源

• main.js
• assets/main.scss

路由与导航

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

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

图表来源

• router/index.js

章节来源

• router/index.js

状态管理（用户）

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

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
• api/request.js

章节来源

• stores/user.js

HTTP 客户端与错误处理

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

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

章节来源

• api/request.js

样式与主题

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

章节来源

• assets/main.scss

调试与测试工具

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

章节来源

• DEBUG_GUIDE.md
• test-api.html
• test_frontend_connection.py

依赖关系分析

• 组件耦合
  • 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

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
• router/index.js
• stores/user.js
• api/request.js

章节来源

• package.json

性能考量

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

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

故障排查指南

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

章节来源

• DEBUG_GUIDE.md
• test_frontend_connection.py

结论

本指南基于仓库现有前端工程与文档，系统梳理了 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
• frontend.md

B. 静态资源处理、代码分割与打包分析

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

章节来源

• frontend.md
• router/index.js

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