# 前端配置

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

## 目录
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

```mermaid
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](file://fms-vue/index.html#L1-L295)
- [main.js:1-78](file://fms-vue/src/main.js#L1-L78)
- [vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)
- [http.js:1-111](file://fms-vue/src/services/http.js#L1-L111)
- [app.js:1-123](file://fms-vue/src/stores/app.js#L1-L123)
- [index.js:1-16](file://fms-vue/src/theme/index.js#L1-L16)
- [tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
- [presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
- [index.css:1-17](file://fms-vue/src/styles/index.css#L1-L17)

章节来源
- [vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)
- [package.json:1-48](file://fms-vue/package.json#L1-L48)
- [vitest.config.js:1-34](file://fms-vue/vitest.config.js#L1-L34)
- [index.html:1-295](file://fms-vue/index.html#L1-L295)
- [main.js:1-78](file://fms-vue/src/main.js#L1-L78)

## 核心组件
- 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](file://fms-vue/vite.config.js#L5-L23)
- [tokens.css:7-151](file://fms-vue/src/theme/tokens.css#L7-L151)
- [index.js:5-15](file://fms-vue/src/theme/index.js#L5-L15)
- [presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
- [app.js:6-123](file://fms-vue/src/stores/app.js#L6-L123)
- [http.js:8-10](file://fms-vue/src/services/http.js#L8-L10)
- [index.html:8-19](file://fms-vue/index.html#L8-L19)
- [main.js:21-58](file://fms-vue/src/main.js#L21-L58)

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

```mermaid
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](file://fms-vue/index.html#L8-L19)
- [main.js:21-58](file://fms-vue/src/main.js#L21-L58)
- [app.js:104-123](file://fms-vue/src/stores/app.js#L104-L123)
- [index.js:5-15](file://fms-vue/src/theme/index.js#L5-L15)
- [tokens.css:7-151](file://fms-vue/src/theme/tokens.css#L7-L151)
- [vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)

## 详细组件分析

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

```mermaid
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](file://fms-vue/vite.config.js#L6-L21)

章节来源
- [vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)

### 主题配置系统
- 设计令牌
  - 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 作为初始值。

```mermaid
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](file://fms-vue/src/stores/app.js#L6-L123)
- [index.js:5-15](file://fms-vue/src/theme/index.js#L5-L15)
- [tokens.css:7-151](file://fms-vue/src/theme/tokens.css#L7-L151)
- [presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)

章节来源
- [tokens.css:7-151](file://fms-vue/src/theme/tokens.css#L7-L151)
- [index.js:5-15](file://fms-vue/src/theme/index.js#L5-L15)
- [presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
- [app.js:6-123](file://fms-vue/src/stores/app.js#L6-L123)

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

```mermaid
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](file://fms-vue/src/services/http.js#L8-L10)
- [http.js:40-104](file://fms-vue/src/services/http.js#L40-L104)

章节来源
- [http.js:1-111](file://fms-vue/src/services/http.js#L1-L111)

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

```mermaid
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](file://fms-vue/index.html#L8-L19)
- [main.js:14-58](file://fms-vue/src/main.js#L14-L58)

章节来源
- [index.html:8-19](file://fms-vue/index.html#L8-L19)
- [main.js:14-58](file://fms-vue/src/main.js#L14-L58)

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

章节来源
- [vitest.config.js:1-34](file://fms-vue/vitest.config.js#L1-L34)

## 依赖关系分析
- 构建与运行
  - 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、组件库样式与字体。

```mermaid
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](file://fms-vue/package.json#L1-L48)
- [index.css:1-17](file://fms-vue/src/styles/index.css#L1-L17)

章节来源
- [package.json:1-48](file://fms-vue/package.json#L1-L48)
- [index.css:1-17](file://fms-vue/src/styles/index.css#L1-L17)

## 性能考量
- 构建与打包
  - 当前未启用额外插件，可通过按需引入、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](file://fms-vue/vite.config.js#L11-L21)
- [index.html:8-19](file://fms-vue/index.html#L8-L19)
- [http.js:40-104](file://fms-vue/src/services/http.js#L40-L104)

## 结论
本项目的前端配置以简洁、可维护为核心：
- 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](file://fms-vue/package.json#L6-L19)
- [http.js:8-10](file://fms-vue/src/services/http.js#L8-L10)
- [presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
- [tokens.css:7-151](file://fms-vue/src/theme/tokens.css#L7-L151)