快速开始
本章面向第一次取得源码的开发者。目标不是只看到登录页，而是完成一次可重复的启动，并确认认证、用户信息、菜单和预置业务数据四条链路都正常。
准备工作
获取源码
请使用交付的纯前端商业版源码目录：
art-design-pro-x/不要把前后端商业版中的前端目录覆盖到本项目。两版界面和工程结构相近，但认证协议、API 文件和数据来源已经分别维护。
环境要求
Node.js >= 20.19.0
pnpm >= 8.8.0检查本机版本：
node --version
pnpm --version如果团队使用 nvm、fnm 或 Volta，建议在项目开始时统一 Node.js 版本，避免本地和 CI 构建结果不一致。
安装依赖
在项目根目录执行：
pnpm install首次安装后应保留 pnpm-lock.yaml。不要再执行 npm install 生成 package-lock.json。
理解环境文件
项目只使用三组环境文件：
| 文件 | 用途 |
|---|---|
.env | 所有模式共用的端口、基础路径、菜单来源和存储配置 |
.env.development | 本地开发代理目标 |
.env.production | 生产 API 地址、部署基础路径和构建行为 |
首次启动重点确认：
# .env
VITE_PORT = 3000
VITE_BASE_URL = /
VITE_API_URL = /
VITE_MENU_SOURCE = local
VITE_WITH_CREDENTIALS = false开发代理配置：
# .env.development
VITE_API_URL = /
VITE_API_PROXY_URL = https://your-api.example.com浏览器会请求 /api/...，Vite 再把 /api 和 /uploads 转发到 VITE_API_PROXY_URL。这可以避免本地开发时直接跨域。
修改环境变量后需要重启开发服务
Vite 在启动时读取环境文件。修改 .env 或 .env.development 后，请停止并重新运行 pnpm dev。
准备最小后端
系统进入主界面至少需要三个接口：
POST /api/v1/auth/signin
POST /api/v1/auth/logout
GET /api/v1/user/info如果暂时没有后端，可以继续使用交付配置中的 Apifox Mock。默认体验账号以当前项目 README.md 为准：
用户名：Super
密码：123456登录接口需要返回非空 accessToken，统一响应格式为：
{
"code": 200,
"msg": "登录成功",
"data": {
"accessToken": "your-access-token"
}
}当前用户接口至少提供：
{
"code": 200,
"msg": "获取成功",
"data": {
"id": 1,
"username": "Super",
"email": "super@example.com",
"roles": ["R_SUPER"],
"buttons": ["*"]
}
}roles 和 buttons 必须是非空字符串组成的数组。如果使用通配按钮权限 *，它不能和其他权限码同时返回。
启动开发服务
pnpm dev默认会打开：
http://localhost:3000终端启动信息会显示当前 API 地址、代理地址、版本号和构建标识。浏览器没有自动打开时，可以手动访问上面的地址。
第一次验证
1. 验证登录
在浏览器 Network 中确认：
POST /api/v1/auth/signin返回code: 200。- 请求体是普通 JSON。
- 响应
data.accessToken是非空字符串。
2. 验证当前用户
登录后确认 GET /api/v1/user/info 成功，并返回 id、username、email、roles、buttons。
3. 验证菜单
默认 VITE_MENU_SOURCE=local，因此不应请求菜单接口。菜单来自 src/router/modules，再按用户 roles 过滤。
4. 验证业务页面
打开用户管理、内容管理或工作流等页面，列表应从 src/mock 正常加载。执行新增、编辑或删除时，页面应明确提示当前不会写入服务端。
5. 验证刷新恢复
在任意受保护页面刷新浏览器：
- Access Token 应从 Pinia 持久化恢复。
- 前端会重新请求
/api/v1/user/info。 - 菜单和动态路由重新生成。
- Token 无效时应返回登录页，而不是停留在空白页面。
常用命令
| 命令 | 用途 |
|---|---|
pnpm dev | 启动开发服务器并打开浏览器 |
pnpm build | TypeScript 检查并生成 dist/ |
pnpm serve | 本地预览生产构建 |
pnpm lint | 执行 ESLint 检查 |
pnpm fix | 自动修复可处理的 ESLint 问题 |
pnpm security:check | 执行前端安全基线检查 |
pnpm release:check | 完整发布检查 |
常见启动问题
登录接口 404
检查 .env.development 中的 VITE_API_PROXY_URL，并确认后端实际存在 /api/v1/auth/signin。修改后重启 Vite。
浏览器出现跨域错误
开发环境优先保持 VITE_API_URL=/，通过 Vite 代理访问后端。只有明确配置好 CORS 时才直接使用完整跨域地址。
登录成功后进入 500 页面
重点检查当前用户响应格式、roles 和 buttons。如果启用了远程菜单，还要检查菜单结构是否通过校验。
页面刷新后重新登录
检查 Access Token 是否写入项目命名空间的 LocalStorage，以及 /api/v1/user/info 是否接受 Bearer Token。当前项目没有自动刷新令牌。
端口 3000 被占用
修改 .env：
VITE_PORT = 3001然后重新运行 pnpm dev。
下一步
首次启动完成后，建议阅读项目结构，然后根据目标选择：