PC 管理端快速启动
RuoYi Office 的 PC 管理端基于 Vue 3、TypeScript、Vite 6、Vben Admin 5 和 Ant Design Vue 实现，主应用目录是 ruoyi-office-vben/apps/web-antd。本文只聚焦前端启动、配置和常见问题；完整前后端启动可先看 /quick-start/。
环境要求
| 环境 | 要求 |
|---|---|
| Node.js | `^20.19.0 |
| pnpm | >= 10.0.0，仓库锁定 pnpm@10.32.1 |
| 后端服务 | 默认 http://127.0.0.1:48080 |
建议在 ruoyi-office-vben/ 根目录执行前端命令，不要进入 apps/web-antd 后单独安装依赖。
安装依赖
powershell
cd ruoyi-office-vben
pnpm install仓库使用 pnpm workspace 和 Vben monorepo 结构，首次安装会生成多个包的 stub 和依赖链接。若安装中断，优先重新执行 pnpm install，不要混用 npm 或 yarn。
启动 web-antd
powershell
cd ruoyi-office-vben
pnpm dev:antd启动成功后，终端会输出 Vite 访问地址。登录接口默认通过代理访问后端 /admin-api，后端推荐先启动 ruoyi-office/yudao-server 单体服务。
构建与检查
powershell
pnpm build:antd
pnpm check:type
pnpm lint日常开发建议至少跑 pnpm check:type，涉及公共组件或复杂页面时再跑 pnpm lint。
目录速览
| 目录 | 用途 |
|---|---|
apps/web-antd/src/api | 后端接口封装，按业务模块组织 |
apps/web-antd/src/views | 页面视图，基本与 API 模块同构 |
apps/web-antd/src/components | 业务公共组件 |
apps/web-antd/src/router | 路由定义 |
apps/web-antd/src/store | Pinia 状态 |
packages/* | Vben 基础能力、工具、样式、图标等 |
后端地址配置
本地开发时，前端通常通过 Vite dev server 代理到后端。若登录、验证码、菜单接口请求失败，按顺序检查：
- 后端
http://127.0.0.1:48080是否能访问。 .env或应用环境文件中的 API 地址是否指向本地后端。- 浏览器 Network 面板中的请求路径是否以
/admin-api开头。 - 后端是否允许当前 Origin 或代理是否生效。
页面开发约定
RuoYi Office 管理端优先复用项目已有模式：
- 页面容器使用
Page。 - 表格页面优先使用
useVbenVxeGrid和TableAction。 - 弹窗使用
useVbenModal。 - API 使用
requestClient。 - 字典使用
DICT_TYPE、getDictOptions、getDictLabel。 - Vue SFC 保持
<script lang="ts" setup>、<template>、<style scoped>顺序。
常见问题
pnpm 版本不匹配
使用 Corepack 或手动安装 pnpm 10.x：
powershell
corepack enable
corepack prepare pnpm@10.32.1 --activate登录后菜单为空
通常是后端数据库静态数据未初始化完整，或当前账号没有菜单权限。先确认数据库执行了最新静态数据，再检查系统管理里的角色菜单授权。
页面接口 404
确认后端模块已启用。例如 CRM 页面需要后端聚合启用 yudao-module-crm；BPM 页面需要启用 yudao-module-bpm 并完成表结构初始化。
相关文档
- 后端快速启动：/quick-start/
- 工作流手册：/bpm/
- CRM 客户管理：/crm/customer/
