前端快速上手

面向 Forge Admin 前端开发者的完整上手指南，覆盖环境要求、依赖安装、启动、构建、环境变量配置。

环境要求

组件	最低版本	推荐版本	说明
Node.js	20.19	20 LTS / 22 LTS	低于此版本 Vite 7 无法运行
pnpm	8	9+	必须使用 pnpm，不要用 npm 或 yarn

验证环境：

bash

node -v   # ≥ v20.19.0
pnpm -v   # ≥ 8.0.0

安装依赖

进入 forge-admin-ui 目录，执行：

bash

cd forge-admin-ui
pnpm install

国内网络加速

下载慢的话，先配置国内镜像：

bash

pnpm config set registry https://registry.npmmirror.com

常见踩坑

pnpm install 报权限错误：sudo chown -R $(whoami) ~/.pnpm-store
某个 native 模块编译失败：检查 Node.js 版本是否 ≥ 20.19，必要时升级
Windows 下路径过长报错：pnpm 使用硬链接/符号链接，一般不会遇到；如果遇到，启用 Windows 开发者模式中的长路径支持

启动开发服务器

bash

pnpm dev

默认端口为 3000（可在 .env.development 的 VITE_HTTP_PORT 中修改）。

启动后访问 http://localhost:3000。开发服务器支持：

热更新（HMR）：修改代码后浏览器自动刷新
API 代理：自动代理后端接口（无需处理跨域）
基于文件的路由：在 src/views/ 下新建 .vue 文件自动生成路由

默认登录凭证

后端服务启动后，使用 admin / 123456 登录。

生产构建

bash

pnpm build

构建产物输出到 dist/ 目录。构建命令已配置：

NODE_OPTIONS=--max-old-space-size=40961 — 分配 40GB 内存上限（应对大型项目构建）
sourcemap: false — 不生成 Source Map（减小体积、降低内存）
chunkSizeWarningLimit: 2000 — chunk 超过 2MB 才警告

构建产物部署

构建后的 dist/ 目录是纯静态文件，可以直接部署到任意 Web 服务器（Nginx、Apache、CDN）。详见部署指南。

预览构建结果

bash

pnpm preview

环境变量配置

Forge Admin 前端使用 Vite 的 --mode 机制管理多环境配置。环境变量文件结构如下：

文件	生效时机	用途
`.env`	所有环境	全局通用配置，所有模式下都会加载
`.env.development`	`pnpm dev`	本地开发环境
`.env.test`	`pnpm build --mode test`	测试环境构建
`.env.production`	`pnpm build`	生产环境构建
`.env.example`	—	配置模板，可提交到 Git

安全提醒

.env、.env.development、.env.production 包含实际环境信息，不要提交到 Git 仓库。仅 .env.example 作为模板提交。

全局变量（.env）

所有环境共享的基础配置：

变量	类型	默认值	说明
`VITE_TENANT`	string	`prod`	租户 ID，多租户模式下区分不同租户
`VITE_CLIENT_ID`	string	`""`	应用程序 ID，用于 OAuth2 客户端标识
`VITE_TITLE`	string	`企业级中后台基础框架`	浏览器标签页标题，也会显示在登录页和顶部导航
`VITE_HOME_PATH`	string	`/`	默认首页路径，用户登录后跳转以及侧边栏"首页"菜单指向
`VITE_PUBLIC_PATH`	string	`/`	静态资源公共路径（Vite `base`），部署到子路径时改为 `/子路径/`
`VITE_DEFAULT_LAYOUT`	string	`top-menu`	默认布局模式：`top-menu`（顶部菜单）/ `side-menu`（侧边菜单）
`VITE_USE_MOCK`	string	`false`	是否启用 Mock 数据，开发阶段可临时改为 `true`

开发环境（.env.development）

本地 pnpm dev 时生效。在这些变量中，最重要的是代理配置——它决定了前端请求如何转发到后端。

端口与请求

变量	说明
`VITE_HTTP_PORT`	开发服务器端口，默认 `3000`
`VITE_REQUEST_PREFIX`	所有 API 请求的统一前缀，默认 `/dev-api`。前端发 `GET /dev-api/system/user/list` 时，代理会去掉前缀后转发

代理配置（关键！）

开发环境下前端通过 Vite 内置代理转发 API 请求，无需处理跨域：

变量	说明
`VITE_HTTP_PROXY_TARGET`	主服务代理目标。默认 `http://www.dlforgelab.com:8084/forge-api/`。所有匹配 `VITE_REQUEST_PREFIX` 的请求（排除 flow/workspace）都转发到这里。如果本地启动了后端服务，改为 `http://localhost:8580/`
`VITE_FLOW_PROXY_TARGET`	流程服务代理目标。默认 `http://127.0.0.1:8081/`。匹配 `/flow` 和 `/workspace` 路径的请求转发到这里。如果没有运行独立的流程服务，可以让它指向主服务地址
`VITE_RESOURCE_HOST`	图片等静态资源的 host 地址，默认 `/`
`VITE_TEMPLATE_PATH`	模板文件下载路径，默认 `/templates`

代理规则速查（无须记忆）

请求 /dev-api/system/user/list
  ──► 去掉 /dev-api ──► http://后端主服务/system/user/list

请求 /dev-api/api/flow/task/xxx
  ──► 去掉 /dev-api ──► http://流程服务/api/flow/task/xxx

请求 /ws
  ──► WebSocket 代理 ──► http://后端主服务（ws://）

客户端与登录

变量	说明
`VITE_APP_ID`	客户端 AppId，默认 `pc`。对应后端 `sys_client` 表的 `client_code`，用于 OAuth2 认证
`VITE_USER_CLIENT`	登录设备标识，默认 `pc`。与 `VITE_APP_ID` 一致即可

报表子系统单点登录

变量	说明
`VITE_SSO_BRIDGE_ROUTE`	触发 SSO 跳转的路由路径，默认 `/report/design`
`VITE_SSO_TARGET_CLIENT`	目标客户端代码，默认 `forge_report`
`VITE_SSO_TARGET_BASE_URLS`	JSON 格式，各子系统的前端入口地址。key 对应 `sys_client.clientCode`。示例：`{"forge_report":"http://localhost:3021/forge-report"}`
`VITE_SSO_DEFAULT_REDIRECTS`	JSON 格式，各子系统 SSO 登录后的默认跳转路径。示例：`{"forge_report":"/project/items"}`
`VITE_REPORT_UI_BASE_URL`	报表子系统前端地址（兜底值，当 `VITE_SSO_TARGET_BASE_URLS` 里没有配置时使用）
`VITE_REPORT_UI_DEFAULT_REDIRECT`	报表子系统默认跳转路径（兜底值）
`VITE_REPORT_UI_HOST_FALLBACK`	报表子系统 host 兜底
`VITE_REPORT_UI_PATH_PREFIX`	报表子系统路径前缀

生产环境（.env.production）

pnpm build 时生效：

变量	说明
`VITE_PUBLIC_PATH`	生产静态资源路径，默认 `/forge`。部署到 Nginx 子路径时使用，如 `/forge` 表示所有资源从 `/forge/assets/...` 加载
`VITE_BASE_URL`	路由前缀，默认 `/forge`。与 `VITE_PUBLIC_PATH` 保持一致
`VITE_REQUEST_PREFIX`	API 请求前缀，生产环境默认 `/forge-api`。由 Nginx 代理转发到后端
`VITE_HTTP_PROXY_TARGET`	生产环境留空（由 Nginx 处理代理）
`VITE_FLOW_PROXY_TARGET`	生产环境留空
`VITE_DEVTOOL`	生产环境设为 `none`（不生成 Source Map）

其余变量（VITE_APP_ID、VITE_USER_CLIENT、报表 SSO 相关）与开发环境相同的含义，但值可能指向正式服务器地址。

测试环境（.env.test）

执行 pnpm build --mode test 时生效，结构与生产环境一致，但指向测试服务器地址。

项目结构速览

forge-admin-ui/
├── .env                              # 全局环境变量
├── .env.development                  # 开发环境变量
├── .env.production                   # 生产环境变量
├── vite.config.js                    # Vite 构建配置（含代理设置）
├── package.json                      # 依赖与脚本
├── pnpm-lock.yaml                    # 依赖锁定文件
├── src/
│   ├── views/                        # 页面（基于文件的路由，自动生成）
│   ├── components/                   # 公共组件（见组件文档）
│   ├── api/                          # API 请求封装
│   ├── router/                       # 路由配置
│   ├── store/                        # Pinia 状态管理
│   ├── layout/                       # 布局组件
│   └── styles/                       # 全局样式（SCSS + UnoCSS）
└── public/                           # 静态资源（直接复制到 dist）

常用命令速查

命令	用途
`pnpm dev`	启动开发服务器（HMR 热更新，端口 3000）
`pnpm build`	生产构建（输出到 `dist/`）
`pnpm build --mode test`	测试环境构建
`pnpm preview`	本地预览构建产物
`pnpm lint:fix`	ESLint 检查并自动修复
`pnpm test`	运行单元测试（Vitest）
`pnpm test:watch`	监听模式运行测试

下一步

组件概览 — 浏览 70+ 公共组件文档
AiCrudPage 核心组件 — 一站式 CRUD 页面解决方案
快速入门 — 全栈项目启动指南
部署指南 — 生产环境部署

前端快速上手 ​

环境要求 ​

安装依赖 ​

启动开发服务器 ​

生产构建 ​

构建产物部署 ​

预览构建结果 ​

环境变量配置 ​

全局变量（.env） ​

开发环境（.env.development） ​

端口与请求 ​

代理配置（关键！） ​

客户端与登录 ​

报表子系统单点登录 ​

生产环境（.env.production） ​

测试环境（.env.test） ​

项目结构速览 ​

常用命令速查 ​

下一步 ​

前端快速上手

环境要求

安装依赖

启动开发服务器

生产构建

构建产物部署

预览构建结果

环境变量配置

全局变量（.env）

开发环境（.env.development）

端口与请求

代理配置（关键！）

客户端与登录

报表子系统单点登录

生产环境（.env.production）

测试环境（.env.test）

项目结构速览

常用命令速查

下一步