workspace/code/fms/.qoder/repowiki/zh/content/配置管理/前端配置.md

前端配置

**本文引用的文件** - [vite.config.js](file://fms-vue/vite.config.js) - [package.json](file://fms-vue/package.json) - [vitest.config.js](file://fms-vue/vitest.config.js) - [index.html](file://fms-vue/index.html) - [main.js](file://fms-vue/src/main.js) - [http.js](file://fms-vue/src/services/http.js) - [tokens.css](file://fms-vue/src/theme/tokens.css) - [index.js](file://fms-vue/src/theme/index.js) - [presets.js](file://fms-vue/src/theme/presets.js) - [app.js](file://fms-vue/src/stores/app.js) - [index.css](file://fms-vue/src/styles/index.css)

目录

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

简介

本文件面向 FMS 前端（基于 Vite + Vue 3）的配置系统，聚焦以下目标：

• 全面说明 Vite 构建与开发服务器配置：端口、主机、代理、路径别名等。
• 详解主题系统：颜色变量、样式令牌、深浅色切换与主色动态替换机制。
• 环境变量管理策略：开发/测试/生产环境的差异与最佳实践。
• 插件与构建优化选项：当前已启用能力与可扩展点。
• 给出可操作的最佳实践：性能优化、代码分割、资源加载策略。
• 提供常见问题定位与解决方案。

项目结构

FMS 前端位于 fms-vue 子工程，关键配置与运行时入口如下：

• 构建与开发服务器：vite.config.js
• 脚本与依赖：package.json
• 测试配置：vitest.config.js
• 应用入口与启动流程：src/main.js、index.html
• HTTP 客户端与环境变量使用：src/services/http.js
• 主题系统与样式：src/theme/*、src/styles/index.css

graph TB
A["index.html<br/>首屏与加载屏"] --> B["src/main.js<br/>应用初始化"]
B --> C["vite.config.js<br/>Vite 构建/开发配置"]
B --> D["src/services/http.js<br/>HTTP 客户端与环境变量"]
B --> E["src/stores/app.js<br/>主题状态与持久化"]
E --> F["src/theme/index.js<br/>写入 CSS 变量/切换深色类"]
F --> G["src/theme/tokens.css<br/>设计令牌与深浅色覆盖"]
E --> H["src/theme/presets.js<br/>预设主色"]
B --> I["src/styles/index.css<br/>引入 tokens 与字体"]

图表来源

• index.html:1-295
• main.js:1-78
• vite.config.js:1-25
• http.js:1-111
• app.js:1-123
• index.js:1-16
• tokens.css:1-152
• presets.js:1-16
• index.css:1-17

章节来源

• vite.config.js:1-25
• package.json:1-48
• vitest.config.js:1-34
• index.html:1-295
• main.js:1-78

核心组件

• Vite 构建与开发服务器
  • 路径别名：将 @ 指向 src，便于统一导入。
  • 开发服务器：host 为 true，port 固定为 5082，strictPort 确保端口独占；/api 请求代理到后端 http://127.0.0.1:8088。
  • 插件：仅启用 @vitejs/plugin-vue。
• 主题系统
  • 设计令牌：集中定义在 tokens.css，浅色 :root，深色 .dark 覆盖同一批变量；主色 --fms-primary 由 JS 注入，衍生色通过 color-mix 派生。
  • 主题切换：通过 app store 的 darkMode 与 primaryColor 驱动 index.js 中的 applyDarkMode 与 applyPrimaryColor，实时修改 DOM。
  • 预设色板：presets.js 提供多套主色，默认主色与 store 初始值一致。
• 环境变量与网络
  • 基础 URL：http.js 使用 import.meta.env.VITE_API_BASE_URL，未设置时回退到 /api（开发期走 Vite 代理）。
  • 鉴权与错误处理：拦截器统一处理 401/40101 会话失效并跳转登录；网络异常或 5xx 统一提示。
• 应用启动与加载体验
  • index.html 内嵌脚本在模块加载前读取本地存储的主题偏好，给 html 添加 boot-dark 类，避免首屏闪烁。
  • main.js 在挂载前初始化主题同步，路由就绪后挂载应用，并以过渡动画隐藏加载屏。

章节来源

• vite.config.js:5-23
• tokens.css:7-151
• index.js:5-15
• presets.js:1-16
• app.js:6-123
• http.js:8-10
• index.html:8-19
• main.js:21-58

架构总览

下图展示从浏览器加载到主题生效、网络请求代理的关键链路。

sequenceDiagram
participant U as "用户"
participant H as "index.html"
participant M as "main.js"
participant S as "stores/app.js"
participant T as "theme/index.js"
participant C as "theme/tokens.css"
participant V as "vite.config.js"
participant API as "后端服务(8088)"
U->>H : 打开页面
H-->>U : 显示加载屏根据本地存储决定是否加 boot-dark
H->>M : 执行入口脚本
M->>S : initThemeSync(pinia)
S->>T : applyDarkMode(darkMode)
T->>C : 切换 .dark 类
S->>T : applyPrimaryColor(primaryColor)
T->>C : 写入 --fms-primary
U->>M : 触发业务请求
M->>V : 开发期 /api 请求
V-->>API : 代理转发到 http : //127.0.0.1 : 8088
API-->>U : 返回数据

图表来源

• index.html:8-19
• main.js:21-58
• app.js:104-123
• index.js:5-15
• tokens.css:7-151
• vite.config.js:11-21

详细组件分析

Vite 构建与开发服务器配置

• 路径别名
  • 将 @ 映射到 src，简化导入路径。
• 开发服务器
  • host: true 允许局域网访问；port: 5082；strictPort: true 避免自动换端口。
  • 代理：/api -> http://127.0.0.1:8088，changeOrigin 开启以兼容后端跨域校验。
• 插件
  • 仅启用 Vue 插件，保持轻量。

flowchart TD
Start(["启动 dev"]) --> Alias["解析路径别名 @ -> src"]
Alias --> Server["启动开发服务器 5082"]
Server --> Proxy{"请求是否匹配 /api ?"}
Proxy --> |是| Forward["转发到 http://127.0.0.1:8088"]
Proxy --> |否| Serve["本地静态资源/模块热更新"]
Forward --> End(["响应"])
Serve --> End

图表来源

• vite.config.js:6-21

章节来源

• vite.config.js:1-25

主题配置系统

• 设计令牌
  • tokens.css 定义中性色、语义色、控件尺寸、阴影、层级等变量；浅色在 :root，深色通过 .dark 覆盖。
  • 主色 --fms-primary 由 JS 注入，hover/active 等衍生色通过 color-mix 计算，保证明暗对比。
• 主题切换机制
  • app store 维护 darkMode 与 primaryColor，并通过 watch 调用 theme/index.js 的方法更新 DOM。
  • 持久化：pinia-plugin-persistedstate 仅持久化 darkMode、primaryColor、locale。
• 预设色板
  • presets.js 提供多套主色，DEFAULT_PRIMARY 作为初始值。

classDiagram
class AppStore {
+boolean darkMode
+string primaryColor
+setDark(value)
+toggleDark()
+setPrimary(color)
}
class ThemeAPI {
+applyDarkMode(isDark)
+applyPrimaryColor(color)
}
class TokensCSS {
+" : root 变量"
+".dark 覆盖变量"
}
class Presets {
+PRESETS[]
+DEFAULT_PRIMARY
}
AppStore --> ThemeAPI : "watch 驱动"
ThemeAPI --> TokensCSS : "写入 CSS 变量/切换类"
AppStore --> Presets : "读取默认主色"

图表来源

• app.js:6-123
• index.js:5-15
• tokens.css:7-151
• presets.js:1-16

章节来源

• tokens.css:7-151
• index.js:5-15
• presets.js:1-16
• app.js:6-123

环境变量管理与网络层

• 环境变量
  • 使用 import.meta.env.VITE_API_BASE_URL 指定 API 基础地址；未设置时回退到 /api。
  • 开发期通过 Vite 代理将 /api 转发至后端；生产环境建议直接配置真实 API 地址。
• 请求与错误处理
  • 请求拦截器注入 Authorization 头；响应拦截器统一封装 ApiResult，处理 401/40101 会话失效并跳转登录。
  • 网络异常或 5xx 统一提示，4xx 业务错误交由调用方处理。

sequenceDiagram
participant UI as "业务组件"
participant HTTP as "http.js"
participant AUTH as "auth store"
participant MSG as "Message"
participant BE as "后端"
UI->>HTTP : post(path, data)
HTTP->>AUTH : 读取 token
HTTP->>BE : 发送请求(带 Authorization)
alt 成功
BE-->>HTTP : 返回数据
HTTP-->>UI : 透传结果
else 鉴权失败(401/40101)
BE-->>HTTP : 鉴权错误
HTTP->>AUTH : 清除会话
HTTP-->>UI : 抛出错误
HTTP->>UI : 跳转登录页
else 网络/服务端错误
BE-->>HTTP : 无响应或 5xx
HTTP->>MSG : 统一错误提示
HTTP-->>UI : 抛出错误
end

图表来源

• http.js:8-10
• http.js:40-104

章节来源

• http.js:1-111

应用启动与加载体验

• 首屏防闪烁
  • index.html 在模块加载前读取 localStorage 中 app 的 darkMode，若为真则给 html 添加 boot-dark，使加载屏与最终主题一致。
• 启动流程
  • main.js 创建 Pinia 并启用持久化插件，先初始化主题同步，再等待路由就绪后挂载应用，最后以过渡动画隐藏加载屏。

flowchart TD
Boot["index.html 加载"] --> Check["读取本地存储主题偏好"]
Check --> ApplyBoot{"是否需要深色?"}
ApplyBoot --> |是| AddClass["html 添加 boot-dark"]
ApplyBoot --> |否| Skip["保持浅色"]
AddClass --> Main["执行 main.js"]
Skip --> Main
Main --> InitTheme["initThemeSync 恢复主题"]
InitTheme --> Mount["挂载应用"]
Mount --> HideBoot["淡出加载屏"]

图表来源

• index.html:8-19
• main.js:14-58

章节来源

• index.html:8-19
• main.js:14-58

测试配置

• Vitest 使用 jsdom 环境，全局开关开启，setupFiles 指定初始化脚本。
• 覆盖率统计排除入口与纯常量文件，阈值 60% 起步。

章节来源

• vitest.config.js:1-34

依赖关系分析

• 构建与运行
  • package.json 定义了 dev/build/preview/test/lint/fmt 等脚本，依赖 vite、@vitejs/plugin-vue、vue 等。
• 运行时依赖
  • axios 用于网络请求；pinia 与 pinia-plugin-persistedstate 负责状态与持久化；stk-table-vue 提供表格能力。
• 样式依赖
  • styles/index.css 引入 tokens.css、组件库样式与字体。

graph LR
Pkg["package.json<br/>脚本与依赖"] --> Vite["vite.config.js"]
Pkg --> Vue["Vue 3 生态"]
Pkg --> Axios["axios"]
Pkg --> Pinia["pinia + persistedstate"]
Pkg --> Table["stk-table-vue"]
Styles["styles/index.css"] --> Tokens["theme/tokens.css"]
Styles --> Font["@fontsource/noto-sans-sc"]

图表来源

• package.json:1-48
• index.css:1-17

章节来源

• package.json:1-48
• index.css:1-17

性能考量

• 构建与打包
  • 当前未启用额外插件，可通过按需引入、Tree Shaking、分包策略进一步优化。
  • 建议：对大体积第三方库进行按需引入或外部化；对路由级视图进行懒加载。
• 开发体验
  • 严格端口与固定端口有助于 CI/CD 稳定性；代理配置减少跨域问题。
• 主题渲染
  • 使用 CSS 变量与 color-mix 减少重复样式；在首屏前注入主题类避免闪烁。
• 网络
  • 合理设置超时与统一错误提示；对鉴权失败做快速重定向，提升用户体验。

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

故障排查指南

• 开发服务器端口占用
  • 现象：启动时报端口被占用。
  • 处理：确认 5082 端口未被占用，或调整 vite.config.js 中的 port。
• 代理无效导致 404
  • 现象：请求 /api 返回 404。
  • 处理：检查 vite.config.js 的 proxy 配置与后端服务是否启动在 8088。
• 主题闪烁
  • 现象：首次加载出现浅色闪屏。
  • 处理：确认 index.html 中读取本地存储并添加 boot-dark 的逻辑存在且正确。
• 登录后仍频繁跳转
  • 现象：进入页面即跳转登录。
  • 处理：检查 http.js 的鉴权拦截逻辑与后端返回码是否为 401/40101。
• 构建产物过大
  • 现象：包体积增长明显。
  • 处理：评估是否引入了未使用的依赖；考虑拆分与懒加载。

章节来源

• vite.config.js:11-21
• index.html:8-19
• http.js:40-104

结论

本项目的前端配置以简洁、可维护为核心：

• Vite 配置聚焦路径别名、开发服务器与代理，满足日常开发与联调需求。
• 主题系统通过 CSS 变量与 JS 驱动实现灵活切换，支持深浅色与主色定制。
• 环境变量与网络层解耦清晰，便于在不同环境部署。
• 建议在后续迭代中逐步引入按需引入、路由懒加载、更细粒度的构建优化，进一步提升性能与可维护性。

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

附录

• 常用命令
  • 开发：pnpm dev
  • 构建：pnpm build
  • 预览：pnpm preview
  • 测试：pnpm test
  • 覆盖率：pnpm test:coverage
  • 代码检查与格式化：pnpm lint / pnpm fmt
• 环境变量约定
  • VITE_API_BASE_URL：API 基础地址（可选），未设置时默认 /api。
• 主题扩展
  • 新增预设色：在 presets.js 中添加新条目。
  • 新增令牌：在 tokens.css 中补充变量，并在组件中使用对应变量。

章节来源

• package.json:6-19
• http.js:8-10
• presets.js:1-16
• tokens.css:7-151