Ruo-Yi基础篇（一）：第一章. 若依极速搭建

Prorise2025-11-012025-11-20

第一章. 若依极速搭建

摘要: 在本章中，我们将完成若依现代化开发环境的搭建，这是我们整个学习之旅的基石。我们将明确技术选型，直接从官方最新的 Spring Boot 3 + Vue 3 版本入手。随后，我们会详细介绍环境准备、项目克隆、数据库初始化以及配置文件修改等关键步骤。本章的唯一目标，是在 15 分钟内，让前后端项目在您的本地计算机上成功运行起来，并能顺利登录系统主界面。

在本章中，我们将像搭建乐高一样，遵循清晰的步骤，快速构建起我们的开发环境：

首先，我们将明确要使用的 若依版本，确保我们站在现代技术的最前沿。
接着，我们会校验并准备好所有必需的 开发环境，这是保证项目顺利运行的前提。
然后，我们将一步步 启动后端服务，包括克隆代码、初始化数据库和修改配置。
最后，我们将 启动前端服务，并完成首次登录，亲眼见证我们的工作成果。

1.1. 版本选择

在开始之前，了解若依的版本生态至关重要，这能帮助我们理解为何做出当前的选择。

1.1.1. 官方与社区版本概览

若依框架为了适应不同的开发场景，官方和社区共同构建了一个丰富的产品矩阵。主要包括：

RuoYi (混合版): 传统的 Spring Boot + Thymeleaf 架构，前后端代码耦合。
RuoYi-Vue (分离版): 主流的前后端分离架构，官方长期维护 Vue 2 版本。
RuoYi-Cloud (微服务版): 基于 Spring Cloud Alibaba 的微服务架构。
RuoYi-App (移动端版): 使用 Uniapp 开发跨平台移动应用。
社区增强版: 如 RuoYi-Vue3 (升级前端到 Vue 3/Vite) 和 RuoYi-Vue-Plus (增强后端功能) 等。

1.1.2. 我们的选择：官方 Spring Boot 3 分支

为了紧跟技术潮流并获得最佳的开发体验，单纯的官方 RuoYi-Vue 主分支（基于 Spring Boot 2 和 Vue 2）已不能满足我们的要求。

幸运的是，若依官方已经提供了一个集成了 Spring Boot 3 和 Vue 3 的现代化分支。我们将直接使用这个分支作为起点，它一步到位地解决了前后端的技术升级问题。

文件路径: https://gitee.com/y_project/RuoYi-Vue/tree/springboot3

这让我们能跳过所有繁琐的迁移和配置，直接开始享受现代化技术栈带来的开发便利。

1.2. 环境准备

请确保您的本地开发环境满足以下最低要求。版本不匹配是导致后续问题的最常见原因。

官方推荐	本教程版本
JDK >= 1.8	JDK 17 LTS (Spring Boot 3 必需)
Mysql >= 5.7.0	MySQL 8.x
Redis >= 3.0	Redis 6.x
Maven >= 3.0	Maven 3.6+
Node >= 12	Node 16+

1.3. 运行后端项目

在上一节我们明确了目标版本后，现在，让我们正式开始克隆项目并启动后端服务。

1.3.1. 克隆项目源码 (直达 Spring Boot 3 分支)

我们将使用 Git 克隆包含前后端所有文件的指定分支。

在您的工作目录下，打开终端并执行以下命令：

1 2	# 克隆项目，并直接切换到 springboot3 分支 git clone -b springboot3 https://gitee.com/y_project/RuoYi-Vue.git ruoyi-modern-project

命令执行完毕后，您会得到一个名为 ruoyi-modern-project 的文件夹。请使用 IntelliJ IDEA 打开这个项目。

1.3.2. 初始化数据库

后端服务的运行依赖于预设的数据库表结构和数据。

请先在您的 MySQL 中创建一个新的数据库，推荐命名为 ry-vue。
找到项目根目录下的 sql 文件夹，将 quartz.sql 和 ry_2023xxxx.sql 这两个 SQL 文件，依次导入到您刚刚创建的 ry-vue 数据库中。

1.3.3. 修改配置文件

接下来，我们需要告诉项目如何连接到我们的数据库和 Redis。

修改数据库连接
文件路径: ruoyi-admin/src/main/resources/application-druid.yml
请根据您的实际情况，修改 master 节点下的 url, username, password。

修改 Redis 连接（可选）
文件路径: ruoyi-admin/src/main/resources/application.yml
请根据您的实际情况，修改 redis 节点下的 host, port, password。

1.3.4. 启动后端服务

所有准备工作就绪，让我们启动后端。

在 IDEA 中，找到 ruoyi-admin 模块。
文件路径: ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java
右键点击该文件，选择 Run 'RuoYiApplication'。

如果控制台成功打印出若依的 LOGO 和启动成功的字样，恭喜，后端服务已成功运行！
IDEA 中 RuoYiApplication 成功启动并显示若依 LOGO 的控制台截图

Windows 用户注意: 首次启动若 logback.xml 报错，请将 <property name="log.path" value="/home/ruoyi/logs" /> 修改为相对路径 <property name="log.path" value="logs" />。

1.4. 运行前端项目

后端大脑已经开始运转，现在我们来点亮前端的“眼睛”。

1.4.1. 定位前端项目

我们克隆的 ruoyi-modern-project 文件夹中，已经包含了前端项目，其目录名为 ruoyi-ui，但他是 vue2 版本的，我们期望使用一个技术栈较新的 vue3 版本，我们可以将整个 ruoyi-ui 文件夹删除，在我们的 ruoyi-modern-project 文件夹中克隆前端 Vue3 项目，我们将会得到 RuoYi-Vue3

这个文件夹，通过 vscode 或其他编译器打开确认版本号无误后进行后续操作

1.4.2. 安装依赖并启动

使用终端进入前端项目目录：
1
cd ./RuoYi-Vue3

安装所有 Node.js 依赖

# 安装依赖
pnpm install
# 注意，由于前端的变化，vue3 仓库已经距离 2025 是三年前的了，一些 js 库依赖 sortablejs，所以需要手动安装，否则无法启动！
pnpm install sortablejs
# 启动 Vite 开发服务器：
# 启动服务
pnpm dev

1.4.3. 验证成功

当终端显示出本地访问地址时，表示前端服务已成功启动。

打开浏览器，访问 http://localhost:80 (或终端提示的其他端口)，输入默认账户/密码 admin/admin123 并登录。如果您能看到功能齐全的后台主界面，则代表整个环境已搭建成功！
若依 Vue3 版本成功登录后的主界面动图

1.5. 本章小结

在本章中，我们高效地完成了所有基础准备工作，为后续的学习扫清了障碍。

明确了技术选型：我们直接采用了官方提供的 Spring Boot 3 + Vue 3 现代化技术栈。
成功运行了项目：通过克隆代码、初始化数据库和修改配置，我们成功地在本地启动了前后端服务，并完成了首次登录。

现在，一个强大、现代化的开发框架已经在我们手中。在下一章，我们将立即体验它最激动人心的功能——代码生成器。