本章将手把手引导你完成项目运行所需的所有环境准备。
2.1 开发环境要求
在开始之前，请确保你的开发机器满足以下最低要求：
| 软件 | 版本要求 | 说明 |
|---|---|---|
| JDK | 17+ | 项目使用 Java 17 编译 |
| Maven | 3.6+ | 项目构建与依赖管理工具 |
| MySQL | 5.7 / 8.0+ | 关系型数据库，存储业务数据 |
| Redis | 5.0+ | 缓存中间件，用于会话、字典缓存 |
| IDE（可选） | IntelliJ IDEA / VS Code | 代码编写与调试 |
2.1.1 验证安装
安装完成后，打开终端分别执行以下命令，确认版本信息：
shell
# 检查 JDK
java -version
# 期望输出：java version "17.x.x" ...
# 检查 Maven
mvn -version
# 期望输出：Apache Maven 3.x.x ...
# 检查 MySQL（连接测试）
mysql -u root -p
# 输入密码后进入 MySQL 命令行，确认服务正常
# 检查 Redis（连接测试）
redis-cli ping
# 期望输出：PONG2.2 数据库初始化
2.2.1 创建数据库
登录 MySQL，执行以下 SQL 创建项目数据库：
sql
-- 创建若依主数据库
CREATE DATABASE IF NOT EXISTS `ry-vue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;2.2.2 导入初始化脚本
项目 sql/ 目录下提供了两个 SQL 脚本文件：
| 脚本文件 | 说明 |
|---|---|
ry_20260417.sql |
若依核心业务表（用户、角色、菜单、部门等），含初始演示数据 |
quartz.sql |
Quartz 定时任务相关表 |
依次导入这两个脚本：
bash
# 方式一：命令行导入
mysql -u root -p ry-vue < sql/ry_20260417.sql
mysql -u root -p ry-vue < sql/quartz.sql
# 方式二：使用图形化工具（Navicat / DBeaver / DataGrip）
# 连接 MySQL → 选择 ry-vue 数据库 → 右键"运行 SQL 文件" → 选择对应脚本执行2.2.3 导入后的表一览
执行成功后，ry-vue 数据库中将包含以下核心表：
| 业务分类 | 表名 | 说明 |
|---|---|---|
| 用户与权限 | sys_user |
系统用户 |
sys_role |
角色信息 | |
sys_menu |
菜单与按钮权限 | |
sys_user_role |
用户-角色关联 | |
sys_role_menu |
角色-菜单关联 | |
| 组织架构 | sys_dept |
部门信息（树形结构） |
sys_post |
岗位信息 | |
sys_user_post |
用户-岗位关联 | |
| 字典与配置 | sys_dict_type |
字典类型 |
sys_dict_data |
字典数据 | |
sys_config |
系统参数配置 | |
| 日志监控 | sys_oper_log |
操作日志 |
sys_logininfor |
登录日志 | |
| 其他 | sys_notice |
通知公告 |
| 定时任务 | QRTZ_* |
Quartz 标准表族（共 11 张） |
2.2.4 初始账号说明
SQL 脚本中预设了以下测试账号（密码经过 BCrypt 加密存储）：
| 账号 | 密码 | 角色 | 说明 |
|---|---|---|---|
admin |
admin123 |
超级管理员 | 拥有全部权限 |
ry |
admin123 |
普通用户 | 拥有部分权限 |
提示 ：初始密码可在登录后修改。密码采用 BCryptPasswordEncoder 加密存储，不可逆。
2.3 配置文件说明
项目配置文件位于 ruoyi-admin/src/main/resources/ 目录下：
arduino
resources/
├── application.yml ← 主配置文件（端口、Redis、Token 等）
├── application-druid.yml ← 数据源配置（Druid 连接池）
├── logback.xml ← 日志配置
├── banner.txt ← 启动 banner
├── mybatis/
│ └── mybatis-config.xml ← MyBatis 全局配置
└── i18n/
└── messages.properties ← 国际化资源下面逐一解析核心配置项。
2.3.1 主配置文件 --- application.yml
（1）项目基础配置
yaml
ruoyi:
name: RuoYi # 项目名称（显示在 Swagger 文档和页面标题）
version: 3.9.2 # 当前版本号
copyrightYear: 2026 # 版权年份
profile: /home/ruoyi/uploadPath # 文件上传路径（Windows 改为 D:/ruoyi/uploadPath）
addressEnabled: false # 是否开启 IP 地址解析
captchaType: math # 验证码类型：math（数学计算）/ char（字符验证）Windows 用户注意 ：将 profile 改为类似 D:/ruoyi/uploadPath 的本地路径。
（2）服务器与日志配置
yaml
server:
port: 8080 # 服务端口，默认 8080
logging:
level:
com.ruoyi: debug # 项目包日志级别：debug（开发）/ info（生产）
org.springframework: warn（3）Redis 配置
yaml
spring:
data:
redis:
host: localhost # Redis 地址
port: 6379 # Redis 端口
database: 0 # 使用的数据库索引
password: # Redis 密码（无密码则留空）
timeout: 10s # 连接超时时间Redis 默认连接 localhost:6379，如果 Redis 有密码请在此处填写。
（4）Token 配置
yaml
token:
header: Authorization # Token 在请求头中的 key 名称
secret: abcdefghijklmnopqrstuvwxyz # JWT 签名密钥（生产环境请更换）
expireTime: 30 # Token 有效期，单位：分钟（5）MyBatis 配置
ruby
mybatis:
typeAliasesPackage: com.ruoyi.**.domain # 实体类别名扫描路径
mapperLocations: classpath*:mapper/**/*Mapper.xml # Mapper XML 文件路径
configLocation: classpath:mybatis/mybatis-config.xml（6）分页与文档配置
yaml
pagehelper:
helperDialect: mysql # 数据库方言
supportMethodsArguments: true
params: count=countSql # count 查询参数
springdoc:
swagger-ui:
path: /swagger-ui.html # Swagger UI 访问路径（7）安全配置
yaml
referer:
enabled: false # 防盗链开关（开发环境建议关闭）
allowed-domains: localhost,127.0.0.1
xss:
enabled: true # XSS 过滤开关
excludes: /system/notice # 排除路径2.3.2 数据源配置 --- application-druid.yml
这是你最需要关注和修改的配置文件：
yaml
spring:
datasource:
type: com.alibaba.druid.pool.DruidDataSource
driverClassName: com.mysql.cj.jdbc.Driver
druid:
master:
# ★ 修改为你的 MySQL 连接信息
url: jdbc:mysql://localhost:3306/ry-vue?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
username: root # ★ 改为你的 MySQL 用户名
password: # ★ 改为你的 MySQL 密码
slave:
enabled: false # 从库默认关闭
# Druid 连接池参数（通常保持默认即可）
initialSize: 5
minIdle: 10
maxActive: 20
maxWait: 60000
# Druid 监控页配置
statViewServlet:
enabled: true
url-pattern: /druid/* # 监控页访问路径
login-username: ruoyi # 监控页登录账号
login-password: 123456 # 监控页登录密码必须修改的三项：
| 配置项 | 说明 |
|---|---|
url 中的 localhost:3306 |
数据库地址和端口 |
username |
数据库用户名 |
password |
数据库密码 |
2.3.3 启动 banner
项目启动时会在控制台打印有趣的 ASCII 字符画，定义在 banner.txt 中，你可以自行修改其中的图案和文字。
2.4 启动项目
2.4.1 方式一：IDE 启动（推荐开发使用）
IntelliJ IDEA 步骤：
- 打开 IDEA，点击
File → Open，选择front-api目录 - IDEA 会自动识别为 Maven 项目，等待依赖下载完成
- 找到启动类
RuoYiApplication.java（路径：ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java） - 点击类名左侧的绿色三角箭头 ▶，选择
Run 'RuoYiApplication' - 观察控制台输出，看到以下 banner 表示启动成功：
scss
(♥◠‿◠)ﾉﾞ 若依启动成功 ლ(´ڡ`ლ)ﾞ
.-------. ____ __
| _ _ \ \ \ / /
| ( ' ) | \ _. / '
|(_ o _) / _( )_ .'
| (_,_).' __ ___(_ o _)'
| |\ \ | || |(_,_)'
| | \ `' /| `-' /
| | \ / \ /
''-' `'-' `-..-'2.4.2 方式二：Maven 命令行启动
bash
# 进入项目根目录
cd front-api
# 编译打包（跳过测试）
mvn clean package -Dmaven.test.skip=true
# 启动 JAR 包
java -jar ruoyi-admin/target/ruoyi-admin.jar或者在 Windows 上直接双击 bin/run.bat 启动。
2.4.3 方式三：热部署开发
项目已集成 spring-boot-devtools，支持热部署：
- IDEA 中：
File → Settings → Build → Compiler →勾选Build project automatically - 快捷键：
Ctrl + Shift + Alt + /→Registry→ 勾选compiler.automake.allow.when.app.running - 修改代码后，IDEA 会自动重启应用（比手动重启快得多）
2.4.4 验证启动
项目启动成功后，验证以下接口：
| 验证项 | 访问地址 | 预期结果 |
|---|---|---|
| Swagger 文档 | http://localhost:8080/swagger-ui.html |
显示 API 接口文档页面 |
| Druid 监控 | http://localhost:8080/druid/ |
显示 Druid 登录页（账号 ruoyi / 密码 123456） |
| API 文档 JSON | http://localhost:8080/v3/api-docs |
返回 OpenAPI 3 规范的 JSON |
2.5 常见启动问题排查
❌ 问题 1：Communications link failure --- 数据库连接失败
原因 ：MySQL 服务未启动，或 application-druid.yml 中的连接信息不正确。
解决：
- 确认 MySQL 服务已启动：
net start mysql（Windows） - 检查
url、username、password是否正确 - 确认数据库
ry-vue已创建
❌ 问题 2：Unable to connect to Redis --- Redis 连接失败
原因 ：Redis 服务未启动，或 application.yml 中的 Redis 配置不正确。
解决：
- 确认 Redis 服务已启动：
redis-server（Linux）/redis-server.exe（Windows） - 用
redis-cli ping测试连接 - 如果 Redis 设置了密码，在
application.yml中填写password
❌ 问题 3：Port 8080 was already in use --- 端口被占用
原因：8080 端口已被其他程序占用。
解决：
- 查找占用端口的进程：
-
- Windows：
netstat -ano | findstr 8080 - Linux：
lsof -i:8080
- Windows：
- 在
application.yml中修改server.port为其他端口（如8081）
❌ 问题 4：Could not find artifact ruoyi-framework --- Maven 依赖缺失
原因：多模块项目初次构建时，子模块还没有安装到本地 Maven 仓库。
解决：
ini
# 在项目根目录执行完整安装
mvn clean install -Dmaven.test.skip=true❌ 问题 5：java.lang.UnsupportedClassVersionError --- JDK 版本不匹配
原因：当前运行的 JDK 版本低于项目要求的 Java 17。
解决：
java -version检查当前版本- 安装 JDK 17+ 并配置
JAVA_HOME环境变量 - 在 IDEA 中：
File → Project Structure → Project SDK选择 JDK 17
❌ 问题 6：ServerTimeZone 相关错误 --- 时区未配置
原因：MySQL 连接 URL 中时区参数问题。
解决 ：确保 URL 包含 serverTimezone=GMT%2B8 参数（已默认配置）。
2.6 环境就绪检查清单
启动前，请逐项确认以下内容：
- JDK 17+ 已安装，
JAVA_HOME已配置 - Maven 3.6+ 已安装，
mvn -version正常 - MySQL 服务已启动，数据库
ry-vue已创建 - SQL 脚本
ry_20260417.sql和quartz.sql已导入 - Redis 服务已启动，
redis-cli ping返回PONG application-druid.yml中数据库用户名和密码已修改- 8080 端口未被占用
全部确认无误后，启动项目，开始你的若依之旅！
下一章我们将深入 项目结构详解，逐目录讲解每个包和类的职责定位。