FastapiAdmin/frontend/web/README.md

FastAPI Admin · 前端工程（web）

基于 Vue 3 + Vite + TypeScript + Element Plus 的后台管理前端，与 FastAPI Admin 后端配套使用。状态管理为 Pinia，样式以 Tailwind CSS 4 与 SCSS 为主，接口请求使用 Axios。

与仓库根文档的关系：项目总览、一键前后端启动、演示账号、Docker 部署等请以 根目录 README.md 为准；本文档侧重 frontend/web/ 目录结构、环境变量与前端开发约定。

快速开始

环境准备

工具	版本要求
Node.js	≥ 20.19（见 package.json → engines）
pnpm	≥ 8.8，推荐 pnpm 9（与 packageManager 字段一致）

未安装 pnpm 时可执行：corepack enable && corepack prepare pnpm@9.15.3 --activate（版本可按项目 packageManager 调整）。

安装依赖并启动

cd frontend/web
pnpm install
pnpm dev

默认开发端口由 .env 中的 VITE_PORT 决定（当前模板为 5173）。

与后端联调

1. 先启动 FastAPI Admin 后端，监听地址与 .env.dev 里 VITE_API_BASE_URL 一致（模板默认为 http://127.0.0.1:8001）。
2. 前端开发时，浏览器请求发往当前页面同源路径，由 Vite server.proxy 把 VITE_APP_BASE_API（如 /api/v1）转发到上述后端。
3. 若页面提示「连接被拒绝」，检查后端是否启动、端口是否一致，或把 VITE_API_BASE_URL 改成你的实际后端地址。

架构概览

main.ts 启动
  └─ initPlugins(app)  ← 插件注册（Pinia → Router → 指令 → i18n → Element Plus）
      └─ mount("#app")
          └─ App.vue
              ├─ onBeforeMount: 主题初始化
              └─ onMounted: bootstrap() → 存储检查/版本升级/站点配置
                  └─ 路由守卫 beforeEach
                      ├─ 存储失效检测
                      ├─ 登录态校验
                      ├─ 动态路由注册（菜单 → addRoute）
                      └─ 标签/标题同步

路由采用 Hash 模式，静态路由（Layout/登录/404）首屏注册，业务路由由守卫根据菜单权限延迟 addRoute。HTTP 拦截器支持 Token 静默续期（401 时自动 refresh，失败后跳转登录）。

技术栈

类别	选型
框架	Vue 3（Composition API / <script setup>）
构建	Vite 7
语言	TypeScript
UI	Element Plus
路由	Vue Router 4（Hash；静态路由 + 守卫内动态 addRoute）
状态	Pinia + pinia-plugin-persistedstate
样式	Tailwind CSS 4、SCSS
HTTP	Axios
国际化	vue-i18n

常用脚本

命令	说明
pnpm dev	本地开发（读取 .env + .env.dev）
pnpm dev:force	强制预打包依赖后启动（缓存异常时）
pnpm build	vue-tsc 类型检查 + 生产构建，产物在 dist/
pnpm build:dev / build:test / build:pro	按 mode 构建（需对应 env 文件）
pnpm preview	本地预览构建结果
pnpm type-check	仅 TypeScript 检查
pnpm lint	ESLint + Prettier + Stylelint
pnpm clean:dev	执行 scripts/clean-dev.ts（清理演示等，使用前阅读脚本说明）
pnpm clean:cache	清理 Vite 等缓存

目录结构（src）

src/
├── api/              # 按业务模块划分的接口封装
├── assets/           # 图片、字体、全局样式等
├── components/       # 通用与业务组件
├── config/           # 应用配置（fastEnter、headerBar 等）
├── enums/            # 枚举
├── hooks/            # 组合式函数
├── layouts/          # 布局壳（art-* 顶栏、侧栏、Tab、设置抽屉等）
├── locales/          # i18n（如 langs/zh.json）
├── plugins/          # Vue 插件注册（入口：plugins/index.ts → initPlugins）
├── router/           # staticRoutes、动态路由、守卫、MenuProcessor
├── store/            # Pinia 模块
├── types/            # TypeScript 类型
├── utils/            # 工具（含 `@utils`）
├── views/            # 页面（module_* / dashboard 等）
├── App.vue
└── main.ts           # 入口

路径别名

别名	指向
@	src/
@views	src/views
@stores	src/store
@utils	src/utils
@styles	src/styles
@imgs / @icons	图片与 SVG

与 vite.config.ts、tsconfig.json 中 paths 保持一致。

环境变量

只有以 VITE_ 开头的变量会注入前端代码：

变量	作用
VITE_PORT	开发服务器端口
VITE_BASE_URL	部署基础路径（子目录部署时形如 /admin/）
VITE_APP_BASE_API	接口路径前缀，与 Vite 代理匹配
VITE_API_URL	浏览器侧发出的 API 根前缀（开发时常为 /）
VITE_API_BASE_URL	代理目标：后端 HTTP 根地址
VITE_ACCESS_MODE	frontend / backend / mixed，菜单与路由来源
VITE_APP_WS_ENDPOINT	WebSocket（如 AI 对话）
VITE_APP_TITLE	页面标题（可被后端参数配置覆盖）

完整列表以仓库内 .env、.env.dev 为准；模板说明见 .env.example。修改任一 env 后需 重启 pnpm dev。

路由与菜单

文件	职责
src/router/staticRoutes.ts	静态路由、dashboardLayoutChildren、壳层菜单合并
src/router/dynamicRoutes.ts	菜单驱动的动态路由
src/router/beforeEach.ts	权限与动态挂载
src/router/MenuProcessor.ts	后端菜单 → 前端路由记录

新增业务页：一般需要 视图 +（可选）静态或动态路由 + 后端菜单/i18n，三者路径与 name 保持一致。

常见问题

现象	建议
ECONNREFUSED / 网络错误	后端未启动或 VITE_API_BASE_URL 端口错误
接口 401 / 频繁跳转登录	Token 失效或未登录；清除站点本地存储后重新登录
修改 .env 不生效	必须 重启 pnpm dev
依赖异常、热更新怪异	尝试 pnpm clean:cache 后再 pnpm dev；仍不行可 pnpm dev:force
类型报错	运行 pnpm type-check；自动生成类型见 src/types/import/（勿手改自动生成的 d.ts）

构建与部署

• 输出目录：dist/
• 部署在子路径时配置 VITE_BASE_URL，并配置网关/Nginx 将前端资源与 /api 等转发到后端
• 生产构建可能移除部分 console（见 vite.config.ts 中 terserOptions）

代码规范与 Git

• 格式化与校验：pnpm lint
• 提交：husky、lint-staged、commitlint；可使用 pnpm commit（Commitizen / cz-git）

element-plus 组件库 基础组件： el-button 按钮 el-container 容器 el-header 头部 el-aside 侧边栏 el-main 主体 el-footer 底部 el-icon 图标 el-row 行布局 el-col 列布局单元 el-link 链接 el-text 文本内容 el-scrollbar 滚动条 el-space 空格 el-splitter、el-splitter-panel 分割面板 Typography 排版 配置组件： el-config-provider 全局配置 Form表单组件： el-autocomplete 自动补全 el-cascader 级联选择器 el-checkbox 多选框 el-color-picker-panel 颜色选择器面板 el-color-picker 颜色选择器 el-date-picker-panel 日期选择器面板 el-radio-group、el-radio-button 日期选择器 el-date-picker 日期时间选择器 el-time-picker 时间选择器 el-time-select 时间选择 el-form、el-form-item 表单 el-input 输入框 el-input-number 数字输入框 el-input-tag 标签输入框 el-input-otp 一次性密码输入框 el-mention 提及 el-radio-group、el-radio 单选框 el-rate 评分 el-select、el-option 选择器 el-select-v2 虚拟化选择器 el-slider 滑块 el-switch 开关按钮 el-transfer 穿梭框 el-tree-select 树形选择 el-upload 上传器 Data数据展示组件： el-avatar 头像 el-badge 徽章 el-calendar 日历 el-card 卡片 el-carousel 走马灯 el-collapse、el-collapse-item 折叠面板 el-descriptions、el-descriptions-item 描述列表. el-empty 空状态 el-image 图片 Infinite Scroll 无限滚动：在要实现滚动加载的列表上添加v-infinite-scroll，并赋值相应的加载方法，可实现滚动到底部时自动执行加载方法。 el-pagination 分页 el-progress 进度条 el-result 结果 el-skeleton 骨架屏 el-table、el-table-col 表格 el-table-v2 虚拟化表格 el-tag 标签 el-timeline、el-timeline-item 时间线 el-tour、el-tour-step 漫游式引导 el-tree 树形控件 el-tree-v2 虚拟化树形控件 el-statistic 统计组件 el-segmented 分段控制器 导航类组件： el-affix 固钉 el-anchor、el-anchor-link 锚点 el-backtop 回到顶部按钮 el-breadcrumb、el-breadcrumb-item 面包屑 el-dropdown、el-dropdown-menu、el-dropdown-item 下拉菜单 el-menu、el-sub-menu、el-menu-item-group、el-menu-item 菜单 el-page-header 页头 el-steps、el-step 步骤条 el-tabs、el-tab-pane 标签页 Feedback 反馈组件： el-alert 提示 el-dialog 对话框 el-drawer 抽屉 loading：Element Plus 提供了两种调用 Loading 的方法：指令和服务。 对于自定义指令 v-loading，只需要绑定 boolean 值即可。 默认状况下，Loading 遮罩会插入到绑定元素的子节点。 通过添加 body 修饰符，可以使遮罩插入至 Dom 中的 body 上。 ElMessage 消息:与 Notification 的区别是后者更多用于系统级通知的被动提醒,默认情况下在顶部显示并在 3 秒后消失。 ElMessageBox 消息弹框： ElMessageBox.confirm 方法以打开 confirm 框。它模拟了系统的 confirm 方法。 ElMessageBox.prompt 方法以打开 prompt 框。它模拟了系统的 prompt 方法。 ElNotification 通知 el-popconfirm 气泡确认框 el-popover 弹出框 el-tooltip 文字提示 Others 其他组件： el-divider 分割线 el-watermark 水印