快速开始
本文面向首次启动商业版前端的研发人员，解决两个问题：
- 如何把
art-design-pro-ui在本地跑起来 - 如何让它和
art-design-pro-server成功联调
首次接手商业版时，建议按本文顺序完成启动和最小联调验证，再进入业务开发。
启动前置说明
商业版前端默认按“前端 + 商业版后端”协同方式设计，不建议把 Mock 运行结果作为使用依据。稳定的启动顺序是：
- 先准备后端
- 再启动前端
- 再验证登录、菜单、站点配置三条链路
环境要求
INFO
推荐环境
- Node.js
20.19.0及以上 - pnpm
8.8.0及以上 - 已可用的
art-design-pro-server
第一步：安装依赖
bash
pnpm install如果依赖安装失败，先确认：
- Node 版本是否满足要求
- 当前网络是否能正常下载 npm 依赖
- 是否误用了过旧的 pnpm
第二步：确认前端环境变量
项目根目录中已经提供：
.env.env.development.env.production
开发环境下最关键的是下面几个变量：
txt
VITE_PORT = 3008
VITE_BASE_URL = /
VITE_API_URL = /
VITE_API_PROXY_URL = http://localhost:13000这组配置的含义是：
- 本地前端开发服务启动在
3008 - 开发环境请求以相对路径发出
- Vite 把
/api请求代理到http://localhost:13000
第三步：启动后端
如果后端还没启动，请先在 art-design-pro-server 中完成：
bash
pnpm setup:dev
pnpm seed:dev
pnpm start:dev前端默认就是按后端端口 13000 联调的。如果你改了后端端口，记得同步调整 VITE_API_PROXY_URL。
第四步：启动前端
bash
pnpm dev默认访问地址通常是：
txt
http://localhost:3008第五步：做一次最小联调验证
建议不仅确认页面是否打开，还要至少验证下面 5 项：
| 检查项 | 预期结果 |
|---|---|
| 登录页 | 页面正常打开，静态资源无 404 |
| 登录请求 | 输入管理员账号后可登录成功 |
| 用户信息 | 登录后能获取当前用户信息 |
| 菜单加载 | 登录后左侧菜单能正常渲染 |
| 站点配置 | 系统名称、欢迎文案等可正常显示 |
推荐的验证顺序
1. 先看浏览器网络请求
重点看：
/api/v1/auth/signin/api/v1/user/info- 菜单相关接口
- 站点公开配置接口
2. 再看页面行为
重点看：
- 登录后是否跳转
- 菜单是否完整
- 刷新页面后登录态是否恢复
3. 最后看控制台错误
尤其注意：
- 401
- 403
- 404
- 路由初始化失败
常用命令
bash
pnpm dev
pnpm build
pnpm serve
pnpm test
pnpm test:e2e
pnpm lint
pnpm fix开发前提交规范
如果你准备开始长期维护或团队协作开发，建议补读 规范。
- 商业版前端已经接入 ESLint、Prettier、Stylelint、Husky、Lint-staged、Commitizen
- 统一提交格式和校验流程后，后续多人协作会稳定很多
- 业务项目往往持续周期更长，越早统一规范，后面越省心
开发阶段最容易遇到的 4 个问题
接口全部报错
通常是后端没启动，或者 VITE_API_PROXY_URL 没对上。
登录成功但页面空白
通常是用户信息、菜单接口或动态路由链路异常。
刷新页面后登录状态失效
通常和 Refresh Token Cookie 或代理配置有关。
页面能打开但按钮不显示
通常和后端菜单、按钮权限、角色授权有关。
检查清单
完成本页后，建议确认：
- 前端服务可通过
http://localhost:3008访问。 - 登录、用户信息、菜单、站点配置接口均返回正常。
- 刷新页面后登录状态可恢复。
- 浏览器控制台没有持续性的 401、403、404 或动态路由初始化错误。