7天学会SpringBoot+Vue3企业级项目RuoyiOffice（二）：启动篇——从源码到前后端联调，跑通开发环境

🌐 文档地址：https://ruoyioffice.com
 👇 文章底部获取源码和演示地址 👇
 💬 ：17156169080（获取产品咨询）

这是《7天学会SpringBoot+Vue3企业级项目RuoyiOffice》系列第 2 篇。第一天看完架构地图，第二天要让它真正跑起来。很多人把"启动成功"理解为控制台出现一行成功日志，结果登录页能打开、点登录却没反应，或者登录后菜单一片空白。本篇把后端、数据库、Redis、前端代理、登录、菜单和首页请求连成一条链路，逐段讲清楚怎么启动、怎么验证、哪里出问题该查哪一层。

▲ 本篇核心视觉：左侧是四个源码目录，中间是运行时的 Vite、Spring Boot、MySQL、Redis 与 UniApp，右侧是登录、权限、菜单和首页请求组成的验收闭环。只有右侧四步都通，开发环境才算跑通。

引言：为什么"进程起来了"不等于"启动成功"

启动一个企业级项目，最常见的误判有三种：后端日志没报错就认为后端好了，前端页面能打开就认为前端好了，登录页出现就认为联调好了。但真实的企业平台至少串着七个环节，任何一个断掉，用户看到的都是"系统不能用"。

所以本文对"启动成功"的定义是：浏览器 Network 面板里，登录、权限、菜单对应的首页请求全部返回 200 且业务码正常，页面能看到真实数据。 后面所有步骤都围绕这个标准展开。

本文命令和配置均来自仓库源码与现有文档，截图使用的是文档站已有的产品截图。你的机器上的端口、数据库地址、账号需要按自己的环境核对。

一、先认路：四个源码目录各管哪一段

第一篇讲过平台分层，这一篇把它落到磁盘上。开发环境涉及四个目录，职责清晰，不要混着操作。

后端模块通常拆成 xxx-api 和 xxx-server，启动时关心的是后者。记住一条原则：后端命令在 ruoyi-office 下执行，PC 前端命令在 ruoyi-office-vben 根目录执行，移动端命令在 ruoyi-office-uniapp 下执行，三者互不替代。

二、环境准备：版本以各工程声明为准

启动失败里有相当一部分来自版本不匹配。下面的要求来自仓库文档和各工程的 package.json，不同时期的文档数字可能不同，以你手里这份源码的声明为准。

动手前先用命令确认版本，比启动失败后再猜要省时间：

java -versionmvn -vnode -vpnpm -v

如果 PC 前端的 pnpm install 提示 Node 或 pnpm 版本不满足，先看 ruoyi-office-vben/package.json 中的 engines 与 packageManager，再决定升级哪一个，不要硬改锁文件。

三、数据库初始化：schema 在前，static_data 在后

后端能不能登录，一半取决于库里有没有数据。初始化文件在 ruoyi-office-db/dump/latest/，文件名里带导出时间戳，以你本地目录中的实际文件为准。

两个独立库要特别注意：xxl_job 和 nacos不要导进业务库 ruoyi-office。执行顺序如下，在 MySQL 客户端里完成：

-- 1. 建库CREATE DATABASE IF NOT EXISTS `ruoyi-office`  DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;USE `ruoyi-office`;-- 2. 先结构，再静态数据（路径和时间戳换成你本机的实际文件）SOURCE E:/ruoyi-office/ruoyi-office-db/dump/latest/schema_时间戳.sql;SOURCE E:/ruoyi-office/ruoyi-office-db/dump/latest/static_data_时间戳.sql;

顺序反了或只导入了 schema，常见结果是后端能启动、登录页也正常，但登录后菜单为空。这是第一类"进程起来了却不能用"的典型案例。

四、两份配置怎么选：application-local 与 application-dev

yudao-server 的 application.yaml 里默认激活的是 local，同时关闭了 Nacos 的注册发现和配置中心，这正是单体模式不需要 Nacos 的原因。两份 profile 的区别如下：

默认 profile 是 local，但交付包里往往没有这个文件。最稳的做法有两种，任选其一：

1. 直接改用 dev
   ：在 IDEA 运行配置的 Active profiles 里填 dev，使用仓库自带的 application-dev.yaml。
2. 基于 dev 自建 local
   ：复制 application-dev.yaml 为 application-local.yaml，按自己的环境改数据库与 Redis，再继续使用默认 profile。

无论哪种，核心是核对两处配置与你的本机一致：

spring:  datasource:    dynamic:      datasource:        master:          url: jdbc:mysql://127.0.0.1:3306/ruoyi-office?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true&rewriteBatchedStatements=true          username: 你的数据库账号          password: 你的数据库密码  data:    redis:      host: 127.0.0.1      port: 6379      database: 0

注意：仓库自带的 dev 示例账号密码未必与你的 MySQL 一致，务必改成自己的；也不要把真实密码提交到仓库。

五、启动后端：先单体，再理解微服务

5.1 单体模式：只启动一个 yudao-server

单体模式是开发和学习的首选：不依赖 Nacos、不走远程调用，所有模块以 Spring Bean 的方式运行在同一个进程里。

1. 用 IDEA 打开 ruoyi-office 目录，等待 Maven 导入依赖。
2. 确认上一节的 profile 与数据库、Redis 配置。
3. 运行 yudao-server 模块下的 YudaoServerApplication。
4. 控制台出现项目启动成功的提示后，访问 http://127.0.0.1:48080，返回 JSON 说明服务可达。

也可以用命令行先确认能编译，再交给 IDEA 运行：

cd ruoyi-officemvn -P boot -DskipTests compile

需要打单体包部署时，使用文档给出的参数，避免子模块各自打出重复的大包：

mvn clean package "-Dmaven.test.skip=true" "-Dskip.repackage=true" -pl yudao-server -am -Pboot

接口文档可以在 http://127.0.0.1:48080/doc.html 查看。

5.2 微服务模式：Gateway + System + Infra + Nacos

微服务模式下，各业务模块独立进程，由 Nacos 做注册与配置，由 Gateway 统一对外。这一节的所有内容只在微服务模式需要，单体模式请跳过。

最小可用集是 Gateway、System、Infra 三个服务；OA、BPM、HRM 等业务服务按需追加。启动顺序和验证步骤如下：

1. 启动 Nacos 单机模式，访问控制台 http://127.0.0.1:8848/nacos，创建命名空间，ID 和名称都设为 dev。
2. 在 ruoyi-office 根目录编译：mvn clean compile "-Dmaven.test.skip=true"。
3. 依次启动 Gateway、System、Infra。
4. 在 Nacos 的服务列表里确认三个服务已注册。
5. 通过网关访问 http://127.0.0.1:48080/admin-api/system/，返回 JSON 说明链路畅通。

两种模式对前端的好处是一致的：无论单体还是微服务，前端都只面向 48080。区别只是 48080 后面是 yudao-server 还是 Gateway。

六、启动 PC 前端：在 monorepo 根目录执行

PC 管理端位于 ruoyi-office-vben，主应用是 apps/web-antd。它是 pnpm workspace 管理的 monorepo，依赖链接和内部包都在根目录统一处理，所以命令必须从 ruoyi-office-vben 根目录执行，不要进入 apps/web-antd 里单独安装依赖。

cd ruoyi-office-vbenpnpm installpnpm dev:antd

dev:antd 是根 package.json 里转发到 @vben/web-antd 的脚本。启动成功后，终端会打印访问地址，端口以终端输出为准，不要凭记忆或旧文档里的数字去访问。

打开终端打印的地址，会看到登录页。登录页出现只说明前端 dev server 在运行，还没有证明任何联调：

▲ PC 登录页：租户选择、账号密码和多种登录方式。注意，这张图证明的是前端页面能渲染，登录接口是否真的打通，要看下一节的 Network 面板。

开发模式默认账号为 admin，密码为 admin123。开发环境的验证码在 .env.development 中默认关闭，方便本地调试；生产和演示环境则开启。

七、联调的核心：Vite 把 /admin-api 代理到后端

浏览器直接请求 5xxx 端口下的 /admin-api，前端 dev server 是没有这些接口的，所以必须有代理。关键配置在 apps/web-antd/vite.config.ts：

server: {  proxy: {    '/admin-api': {      changeOrigin: true,      xfwd: true,      rewrite: (path: string) => path.replace(/^\/admin-api/, ''),      target: 'http://localhost:48080/admin-api',      ws: true,    },  },},

这段配置容易看晕：rewrite 去掉了 /admin-api 前缀，target 又把它补了回来。净效果是请求仍然落在后端的 /admin-api/...，只是主机和端口从前端 dev server 换成了 localhost:48080。与它配套的 .env.development 里有两项：

登录时到底发生了什么，可以用一条请求链路看清。前端登录成功后，会立刻拉取权限信息并把菜单、权限码写入状态，再跳转首页：

这条链路里，login 返回 Token，get-permission-info 返回用户信息、角色、菜单和权限码，前端据此生成侧边栏和路由。菜单并不是前端写死的，而是后端按角色返回的。 这也是"登录成功但菜单为空"几乎总能追到后端数据或权限的原因。

八、用 Network 面板验收：三类请求逐个确认

打开浏览器开发者工具的 Network 面板，勾选保留日志后登录，按下面的清单逐项确认。

查看时有几个细节：

1. 请求地址应以 /admin-api 开头，主机是前端 dev server 的地址，说明请求先经过了代理。如果直接指向 localhost:48080，说明绕过了代理，要确认这是不是你想要的。
2. 开启租户时，请求头会带租户编号，可在 Request Headers 里核对。
3. 部分接口配置了加解密，请求或响应可能带有加密相关的头与密文。这不是故障，以实际抓包为准，不要因为看到密文就判断接口异常。
4. 登录成功后如果跳回登录页，先看 get-permission-info 的状态码，401 通常是 Token 没带上或已失效。

三项都通过，首页才会真正渲染出业务数据：

▲ PC 工作台首页：应用中心、我的单据、通知公告和日程待办都来自登录后的真实接口。看到这样的页面，才说明登录、权限、菜单和首页请求整条链路是通的。

如果想理解"一条请求为什么要依次经过入口、身份、租户和数据权限"，可以看下面这张请求旅程示意图。它同时标注了 -P boot 与 -P cloud 两种部署模式，联调出问题时，可以按这个顺序反推卡在哪一层：

▲ 请求旅程示意：客户端携带 Authorization 与租户编号出发，经过网关入口、Spring Security 身份校验、租户与数据权限过滤，最终进入业务模块。图为示意，不代表你本机一定经过 Gateway：单体模式下没有网关这一跳。

九、启动移动端：UniApp 的后端地址最容易配错

移动端位于 ruoyi-office-uniapp，基于 UniApp + Vue 3 + unibest，同一套代码可以编译到 H5、微信小程序和 App。它不依赖 HBuilderX，主要通过命令行运行。

cd ruoyi-office-uniapppnpm installpnpm dev        # H5，浏览器访问pnpm dev:mp     # 微信小程序

移动端联调的关键是 env 目录下的环境文件。开发模式读取 env/.env.development，本地后端的配置如下：

VITE_SERVER_BASEURL = 'http://127.0.0.1:48080/admin-api'VITE_UPLOAD_BASEURL = 'http://127.0.0.1:48080'VITE_STATIC_BASEURL = 'http://127.0.0.1:48080'VITE_APP_PROXY_ENABLE = trueVITE_APP_PROXY_PREFIX = '/admin-api'

这几项要结合运行目标来理解：

默认的 .env 可能指向线上演示地址，联调本地后端前，先确认当前模式读取的是哪个环境文件，以及请求地址指向哪里。账号与 PC 端一致，开发默认 admin / admin123。

H5 登录并进入首页后，页面应能展示待办、邮箱、考勤等入口和真实的公告数据：

▲ 移动端登录后的首页：用户姓名、部门、角色、待办角标和公告都来自后端接口。它证明移动端请求地址配置正确，Token 与用户信息链路畅通。

移动端的登录接口与 PC 端同源，同样是 /system/auth/login，登录后拉取 /system/auth/get-permission-info。因此 PC 端联调通过、移动端失败时，问题多半在请求地址、代理开关或网络环境，而不是后端业务。

十、常见故障矩阵：先判断断在哪一层

遇到问题别急着改代码，先判断断在七个环节的哪一个。下面的矩阵按"现象 → 可能的层 → 怎么定位 → 怎么处理"整理。

排障时记住一个顺序：后端是否存活 → 数据库和 Redis 是否可用 → 代理是否生效 → 登录接口 → 权限接口 → 首页接口。每一步用最小的验证手段确认，比在业务代码里猜要快得多。

十一、第二天的学习结果

做完启动篇，建议逐项确认：

1. 能说清七个验收环节，并能用 Network 面板证明登录、权限、菜单和首页请求都通过。
2. 能解释 schema 与 static_data 的顺序，以及顺序错误会导致什么现象。
3. 能区分 application-local.yaml 与 application-dev.yaml，并知道没有 local 时怎么办。
4. 能说明单体模式不需要 Nacos、微服务模式才需要，且前端始终只面向 48080。
5. 能在 ruoyi-office-vben 根目录完成 pnpm install 与 pnpm dev:antd，并解释 /admin-api 代理的净效果。
6. 能为 UniApp 配好后端地址，区分 H5、开发者工具和真机的写法。

常见问题（FAQ）

RuoYi Office 开发环境最少需要启动哪些东西？

最少需要 MySQL、Redis 和后端 yudao-server，前端再启动 PC 的 pnpm dev:antd。单体模式不需要 Nacos；只有微服务模式才需要 Nacos、Gateway 以及 System、Infra 等多个服务。

怎样判断 RuoYi Office 已经启动成功？

不要只看后端日志。应在浏览器 Network 面板确认登录、get-permission-info 和首页业务请求都返回成功，并且页面能显示菜单与真实数据。这四项都通，才算前后端联调跑通。

登录成功后为什么左侧菜单是空的？

菜单由后端 get-permission-info 按角色返回。最常见原因是只导入了 schema 而没有导入 static_data，其次是当前角色没有授权菜单。先看该接口返回的 menus 是否为空，再决定检查数据还是授权。

前端启动后到底该访问哪个端口？

以 pnpm dev:antd 终端打印的地址为准。不同版本的文档里可能出现不同的数字，不要凭记忆访问。后端默认端口是 48080，前端代理会把 /admin-api 转发过去。

UniApp 移动端的后端地址在哪里配置？

在 ruoyi-office-uniapp/env 目录下的环境文件里配置，开发模式读取 .env.development 的 VITE_SERVER_BASEURL。H5 可以用代理，真机调试要把 127.0.0.1 换成电脑的局域网 IP。

结语

启动篇最重要的不是记住命令，而是建立一种验收习惯：每一层都有自己的证据。后端靠端口和日志，数据库靠表和静态数据，代理靠请求地址，登录靠 Token，菜单靠权限接口，首页靠真实数据。一条链路能被逐层验证，才谈得上排障和后续开发。

系列进度与下一篇预告

环境跑通之后，就可以进入真正的业务代码了。下一篇是 后端篇：从业务建模开始，设计表结构、VO、Service 和 Mapper，做出一个完整的后端业务接口，并让它被今天跑通的前端真正调用起来。

如果这篇对你有用，点个「在看」或收藏。

🌐 演示地址：https://ruoyioffice.com/web
 📦 GitHub 源码：https://github.com/yuqing2026/ruoyi-office
 📦 Gitee 源码：https://gitee.com/yqzy1688/ruoyi-office
 💬 微信：17156169080（获取产品咨询）

打开演示地址直接查看系统。