快速开始

本文面向首次启动商业版前端的研发人员，解决两个问题：

• 如何把 art-design-pro-x-ui 在本地跑起来
• 如何选择 Java 或 Nest.js 后端，并完成前端联调

首次接手商业版时，建议按本文顺序完成启动和最小联调验证，再进入业务开发。

启动前置说明

商业版前端默认按“前端 + 商业版后端”协同方式设计，不建议把 Mock 运行结果作为使用依据。稳定的启动顺序是：

1. 先准备后端
2. 再启动前端
3. 再验证登录、菜单、站点配置三条链路

环境要求

INFO

推荐环境

• Node.js 20.19.0 及以上
• pnpm 8.8.0 及以上
• 已准备好的 Java 或 Nest.js 配套后端；前端命令统一在 art-design-pro-x-ui 根目录执行

Java 后端还需要 JDK 21、MySQL 和 Redis；Nest.js 后端依赖与初始化方式见其交付 README 或 Nest.js 后端快速开始。两个后端任选其一即可。

第一步：安装依赖

pnpm install

如果依赖安装失败，先确认：

• Node 版本是否满足要求
• 当前网络是否能正常下载 npm 依赖
• 是否误用了过旧的 pnpm

第二步：确认前端环境变量

项目根目录中已经提供：

• .env
• .env.development
• .env.production

先确认 .env.development 中的公共配置：

VITE_PORT = 3000
VITE_BASE_URL = /
VITE_API_URL = /

再按后端版本选择代理地址，只保留一行未注释的 VITE_API_PROXY_URL：

# Java 后端
VITE_API_PROXY_URL = http://localhost:13001

# Nest.js 后端：使用时注释上面一行，再启用下面一行
# VITE_API_PROXY_URL = http://localhost:13000

前端通常运行在 3000，浏览器向当前前端站点的 /api 发出请求，Vite 再转发到选定后端。以实际交付配置和服务端口为准，修改代理后重启前端。不要通过修改 HTTP 封装或接口前缀来切换后端。

第三步：启动所选后端

Java 版

在 art-design-pro-x-java 根目录操作。使用随包 Docker 方案时，先启动 Docker，再执行：

sh scripts/deploy.sh dev

该命令准备开发配置并启动 MySQL / Redis，不会启动本机 Java 后端。等待数据服务健康后，再执行：

node scripts/dev.mjs

后端脚本使用 JDK 21，编译并启动 Spring Boot，读取根目录 config/application-dev.yml。首次启动由 Flyway 初始化数据库，无需执行 Nest.js 的 seed 命令或手动导入 SQL。健康检查地址为 http://localhost:13001/actuator/health，应返回 status: UP。

已有 MySQL / Redis 时，按 Java 仓库 README 配置外置开发 YAML 后直接启动 Java 后端，不需要再启动随包 Docker 数据服务。IDE 启动方式、Windows 环境与首次登录账号见 Java 快速开始。

Nest.js 版

在 art-design-pro-x-server 根目录按交付 README 完成依赖安装与首次开发环境初始化：

pnpm install
pnpm setup:dev
pnpm seed:dev
pnpm start:dev

setup:dev 和 seed:dev 用于首次开发环境准备，不作为已有客户库的日常启动或生产升级命令。已有环境日常执行 pnpm start:dev；具体前置条件见 Nest.js 后端快速开始。

Nest.js 后端默认端口为 13000。无论使用哪个后端，若修改了后端端口，都要同步更新前端 VITE_API_PROXY_URL。

第四步：启动前端

回到 art-design-pro-x-ui 根目录，另开终端执行：

pnpm dev

默认访问地址通常是：

http://localhost:3000

第五步：做一次最小联调验证

建议不仅确认页面是否打开，还要至少验证下面 5 项：

检查项	预期结果
登录页	页面正常打开，静态资源无 404
登录请求	输入管理员账号后可登录成功
用户信息	登录后能获取当前用户信息
菜单加载	登录后左侧菜单能正常渲染
站点配置	系统名称、欢迎文案等可正常显示

推荐的验证顺序

1. 先看浏览器网络请求

重点看：

• /api/v1/auth/signin
• /api/v1/user/info
• /api/v3/system/menus
• /api/v1/site-settings/public

2. 再看页面行为

重点看：

• 登录后是否跳转
• 菜单是否完整
• 刷新页面后登录态是否恢复

3. 最后看控制台错误

尤其注意：

• 401
• 403
• 404
• 路由初始化失败

常用命令

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 或代理配置有关。

页面能打开但按钮不显示

通常和后端菜单、按钮权限、角色授权有关。

检查清单

完成本页后，建议确认：

• 已选定 Java 或 Nest.js 后端，代理只启用一个目标，端口与实际服务一致。
• 前端服务可通过 http://localhost:3000 访问。
• 登录、用户信息、菜单、站点配置接口均返回正常。
• 刷新页面后登录状态可恢复。
• 浏览器控制台没有持续性的 401、403、404 或动态路由初始化错误。

后续阅读

• 项目目录组织：看 项目结构
• 请求层和代理规则：看 接口联调
• 登录后菜单和路由生成：看 路由与权限