若依 RuoYi-Vue3 + Spring Boot 3 开发笔记

若依 RuoYi-Vue3 + Spring Boot 3 开发笔记
环境：Linux 开发环境
技术栈：Vue3 + Vite + Element Plus + Spring Boot 3 + JDK 17 + MySQL 8 + Redis
目标：从环境搭建到代码生成、关联表、主子表、权限与品牌修改的完整实践记录。

一、版本与代码获取

1. 后端

仓库：RuoYi-Vue

Spring Boot 3 必须使用 springboot3 分支，不能直接用默认 master。
bash

git clone -b springboot3 https://gitee.com/y_project/RuoYi-Vue.git

2. 前端

前端是独立仓库，不在后端 ruoyi-ui 目录中。
bash

git clone https://github.com/yangzongzhuan/RuoYi-Vue3.git

GitHub 慢时可用 GitCode 镜像：
bash

git clone https://gitcode.com/yangzongzhuan/RuoYi-Vue3.git

3. 环境要求
   组件 版本要求
   JDK 17+
   Maven 3.6+
   MySQL 8.x
   Redis 6.x+，必须启动
   Node.js 18+ / 20 LTS
   二、数据库与配置初始化
4. 创建数据库

数据库名建议：ry-vue，字符集 utf8mb4。

依次导入后端 sql/ 目录下：
bash

mysql -u root -p ry-vue < sql/ry_xxxxxx.sql
mysql -u root -p ry-vue < sql/quartz.sql

先导入主 SQL，再导入 quartz.sql。
2. 修改数据库配置

文件：
text

ruoyi-admin/src/main/resources/application-druid.yml

重点修改：
yaml

spring:
datasource:
druid:
master:
url: jdbc:mysql://localhost:3306/ry-vue?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=GMT%2B8
username: root
password: 你的密码

3. 修改 Redis 配置

文件：
text

ruoyi-admin/src/main/resources/application.yml

确认 Redis 地址、端口、密码。Redis 未启动会导致启动失败或登录异常。
三、Linux 开发环境启动

1. 启动后端
   bash

cd RuoYi-Vue
mvn spring-boot:run

启动成功标志：控制台出现 “若依启动成功” 字符画。

默认端口：8080。
2. 启动前端
bash

cd RuoYi-Vue3
npm install --registry=https://registry.npmmirror.com
npm run dev

默认账号密码：
text

admin / admin123

四、常见启动问题

1. npm install 卡住

处理顺序：

加详细日志定位：

bash

npm install --registry=https://registry.npmmirror.com --loglevel verbose

设置全局镜像：

bash

npm config set registry https://registry.npmmirror.com
npm config get registry

检查并清理代理：

bash

npm config get proxy
npm config get https-proxy
npm config delete proxy
npm config delete https-proxy

清理缓存：

bash

npm cache clean --force

仍不行可换 pnpm 或 yarn，不建议使用 cnpm。

2. EACCES: permission denied 0.0.0.0:80

原因：Linux 下 80 属于特权端口，普通用户无法监听。

解决方式：

方式一：命令行临时指定端口
bash

npm run dev -- --port 3000

方式二：修改 vite.config.js
js

server: {
host: '0.0.0.0',
port: 3000
}

如果配置读取环境变量，则在 .env.development 增加：
env

VITE_APP_PORT = 3000

不要用 sudo npm run dev，会导致缓存文件权限混乱。
3. Could not resolve "@vue/shared"

通常为 node_modules 不完整或损坏。

处理顺序：
bash

npm install --save @vue/shared

仍不行则彻底重装：
bash

rm -rf node_modules package-lock.json
npm cache clean --force
npm install

也可换 pnpm，并在 .npmrc 中加：
ini

public-hoist-pattern[]=@vue/*

4. 前端代理报错 ECONNREFUSED 127.0.0.1:8080

说明后端未启动或端口不对。

检查：
bash

ss -tlnp | grep 8080

确认后端启动成功。必要时将前端代理目标从 localhost 改为 127.0.0.1。
五、代码生成器基础流程

标准流程：
text

建表 → 导入代码生成器 → 配置字段 → 生成代码 → 放置文件 → 执行 menu.sql

1. 建表要求

表和字段都要写清楚中文注释，注释会变成页面标签和表格标题。

示例图书表：
sql

CREATE TABLE books (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '图书编号',
name VARCHAR(100) NOT NULL COMMENT '书名',
author VARCHAR(50) COMMENT '作者',
price DECIMAL(10,2) COMMENT '价格',
quantity INT DEFAULT 0 COMMENT '库存数量',
create_time DATETIME COMMENT '创建时间'
) COMMENT = '图书信息';

2. 生成器关键配置
   配置项 示例
   包路径 com.ruoyi.book
   模块名 book
   业务名 bookInfo
   上级菜单 可新建“图书管理”目录
   生成模板 单表选 crud，主子表选 sub

3. 文件放置

   后端 domain、mapper、service 放入业务模块，如 ruoyi-book。

   Controller 放入 ruoyi-admin 的 com.ruoyi.web.controller.book。

   Mapper XML 放入业务模块 resources/mapper/book/。

   前端 api 放入 src/api/book/，views 放入 src/views/book/。

4. menu.sql 只执行一次

menu.sql 用于新增菜单，只在第一次为某张表生成代码时执行。

后续加字段、改关联、换模板重新生成，不要重复执行 menu.sql，否则侧边栏会出现多个同名菜单。

重复菜单处理：

进入“系统管理 → 菜单管理”。

保留一条，删除其余重复项。

若角色权限异常，到“角色管理”重新勾选保留的菜单。

六、独立业务模块：ruoyi-book

1. 创建模块

在 IDEA 中新建 Maven 子模块，命名 ruoyi-book。
2. 根 pom.xml

确认包含：
xml

ruoyi-book

并在 中声明：
xml

com.ruoyi ruoyi-book ${ruoyi.version}

3. ruoyi-book/pom.xml

最稳妥：复制 ruoyi-system/pom.xml，只改：
xml

ruoyi-book
ruoyi-book

4. ruoyi-admin/pom.xml

加入依赖：
xml

com.ruoyi ruoyi-book ${ruoyi.version}

5. 启动类扫描
   java

@SpringBootApplication(scanBasePackages = {"com.ruoyi"})

6. 常见问题：程序包 com.ruoyi.book.domain 不存在

排查顺序：

确认 Book.java 位于：

text

ruoyi-book/src/main/java/com/ruoyi/book/domain/Book.java

确认根 pom.xml 有 ruoyi-book。

确认 ruoyi-admin/pom.xml 依赖了 ruoyi-book。

命令行编译验证：

bash

mvn clean install -pl ruoyi-book -am -DskipTests

命令行成功但 IDEA 报红：刷新 Maven 面板，执行 Reload Project，再 Rebuild Project。

经验：命令行能编译、IDEA 报红，九成是 Maven 模块未刷新。

七、字典字段

适用场景：状态、类型等枚举值，数据变化不频繁。

流程：

给业务表加字段，如 category VARCHAR(50)。

“系统管理 → 字典管理”新增字典类型，如 book_category。

添加字典数据：文学、科技、历史等。

代码生成器“同步”表结构。

字段配置：显示类型 select，字典类型 book_category。

重新生成并替换代码。

前端生成代码会使用：
javascript

const { book_category } = useDict('book_category')

表格使用：
vue

八、关联表字段

适用场景：分类、出版社、供应商等来自另一张业务表的数据。

1. 建分类表并生成 CRUD
   sql

CREATE TABLE book_category (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '分类编号',
name VARCHAR(50) NOT NULL COMMENT '分类名称',
sort INT DEFAULT 0 COMMENT '排序',
status CHAR(1) DEFAULT '0' COMMENT '状态',
create_time DATETIME COMMENT '创建时间'
) COMMENT = '图书分类';

先为 book_category 生成 CRUD 和菜单，并录入分类数据。
2. 修改图书表
sql

ALTER TABLE books DROP COLUMN category;
ALTER TABLE books ADD COLUMN category_id BIGINT DEFAULT NULL COMMENT '图书分类';

3. 后端字段统一

Book.java：
java

private Long categoryId;

BookMapper.xml 四处必须统一：
xml

select id, name, author, price, quantity, create_time, category_id from books

category_id,
#{categoryId},

category_id = #{categoryId},

4. 前端动态下拉

引入分类接口：
javascript

import { listBookCategory } from "@/api/book/bookCategory"

定义：
javascript

const categoryOptions = ref([])

function getCategoryOptions() {
listBookCategory({ pageNum: 1, pageSize: 1000 }).then(response => {
categoryOptions.value = response.rows || []
})
}

function getCategoryName(id) {
if (id === null || id === undefined) return ""
const item = categoryOptions.value.find(c => c.id === id)
return item ? item.name : id
}

下拉框：
vue

表格显示名称：
vue

{{ getCategoryName(scope.row.categoryId) }}

5. 核心原则

以下四处必须统一：
text

数据库列名 category_id
Java 属性 categoryId
Mapper 映射 categoryId / category_id
前端字段 categoryId

缺一处就可能出现查询报错、下拉不显示或保存为空。
九、主子表

1. 建子表

子表必须有指向主表主键的非空外键。
sql

CREATE TABLE borrow_record (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '借阅记录ID',
book_id BIGINT NOT NULL COMMENT '图书ID',
borrower VARCHAR(50) NOT NULL COMMENT '借阅人',
borrow_date DATE COMMENT '借阅日期',
return_date DATE COMMENT '归还日期',
status CHAR(1) DEFAULT '0' COMMENT '状态',
create_time DATETIME COMMENT '创建时间',
KEY idx_book_id (book_id)
) COMMENT = '借阅记录';

关键：book_id BIGINT NOT NULL。
2. 生成器配置

编辑主表 books：

生成模板：选“主子表（增删改查）”

关联子表名：borrow_record

子表外键名：book_id

子表 borrow_record 不单独配置主子表模板。
3. 前端结构说明

RuoYi-Vue3 标准版主子表不会生成独立的子表组件文件，子表表格直接内嵌在主表 index.vue 的新增/编辑弹窗中。

如果找不到子表区域，检查：

生成模板是否选对主子表。

关联子表和外键是否配置。

重新生成后是否覆盖了主表 index.vue。

4. 已知限制

   默认不包含主子表同一事务，需要自己加 @Transactional。

   默认不级联删除子表，需要手动补删除逻辑。

   官方标准版通常只支持一对一主子表生成。

5. 代码覆盖注意

代码生成器每次生成完整文件，会覆盖手动修改过的 index.vue。

主子表重新生成后，之前手动加的“分类动态下拉”会丢失，需要基于新文件重新补：

categoryOptions

getCategoryOptions

getCategoryName

搜索栏、表单、表格三处分类控件

十、品牌与标题修改

1. 浏览器标题与侧边栏标题

优先修改环境变量：
text

.env.development
.env.production

env

VITE_APP_TITLE = 你的系统名称

修改后重启前端。
2. 浏览器标签页标题

文件：
text

RuoYi-Vue3/index.html

修改：
html

<title>你的系统名称</title>

3. 侧边栏 Logo 标题

文件：
text

RuoYi-Vue3/src/layout/components/Sidebar/Logo.vue

替换其中写死的标题文字。
4. 登录页标题

文件：
text

RuoYi-Vue3/src/views/login.vue

搜索“若依”并替换。
5. 图标

浏览器图标：public/favicon.ico

侧边栏 Logo：src/assets/logo/logo.png

登录背景：src/assets/images/login-background.jpg

十一、权限体系

若依权限核心：RBAC。
text

用户 → 角色 → 菜单/按钮

一个按钮权限需要四处一致：

数据库 sys_menu.perms，如 book:bookInfo:add

后端接口：

java

@PreAuthorize("@ss.hasPermi('book:bookInfo:add')")

前端按钮：

vue

v-hasPermi="['book:bookInfo:add']"

后台“角色管理”中正确分配菜单和按钮权限。

数据权限通过 @DataScope 注解结合角色数据范围实现。
十二、常用命令速查
bash

后端启动

mvn spring-boot:run

单独编译业务模块

mvn clean install -pl ruoyi-book -am -DskipTests

前端安装依赖

npm install --registry=https://registry.npmmirror.com

前端启动

npm run dev

临时指定端口

npm run dev -- --port 3000

检查后端端口

ss -tlnp | grep 8080

清理 npm 缓存

npm cache clean --force

十三、核心避坑清单

Spring Boot 3 必须用 springboot3 分支，JDK 必须 17+。

前端是独立仓库 RuoYi-Vue3。

Linux 普通用户不能监听 80 端口，开发端口改 3000。

Redis 必须启动，否则登录和验证码异常。

menu.sql 只执行一次，重复执行会产生重复菜单。

代码生成器重新生成会覆盖手改前端文件。

新建 Maven 模块后，命令行编译成功但 IDEA 报红，刷新 Maven 即可。

关联表字段必须四处统一：数据库、Java、Mapper、前端。

主子表子表外键必须 NOT NULL。

品牌标题优先改 VITE_APP_TITLE，再补 index.html、Logo.vue、login.vue。