若依RuoYi-Vue项目改名实操：包名、模块名与前端标识全面换新

把若依RuoYi-Vue的包名、模块名、项目名称整体改一遍，是很多团队迟早要面对的一件事。尤其是企业里拿若依当二次开发底座的项目，到了交付节点，源码里到处是com.ruoyi、ruoyi-admin这种字样，登录页右下角还挂着“若依管理系统”，甲方一眼就能看出这是拿开源框架改的。要么被要求整改，要么你自己也觉得这种“身份信息”不换掉，后面做私有化部署、多项目隔离、代码审计都别扭。这篇文章把我前后折腾过多次的一套完整改名流程整理出来，后端 Java 包名、Maven 模块名、配置文件、数据库脚本、前端 Vue 的标题和版权信息，逐项讲清楚哪些必须动、哪些千万别乱动，并附上我踩过的坑和排查方法。照着做，半小时左右能把一个若依项目改头换面，而且不会改出半夜才发现的隐患。

1. 改包名到底在改什么

1.1 不改包名的三个实际后果

先说清楚为什么要改，不然很多同学改到一半会怀疑自己是不是在瞎折腾。第一是交付问题，甲方或客户拿到源码，随便一搜全是com.ruoyi，框架痕迹清清楚楚，商务层面不好看，技术层面过不了代码规范审计。第二是多项目冲突问题，如果公司里多个项目都用若依做底座，大家都不改包名，将来一旦要合并服务、共享中间件、或者打成同一个容器部署，同名类、同名 Bean、META-INF下的 Spring 配置文件会互相覆盖，排查起来极其痛苦。第三是 Maven 私服规范问题，公司内部的 groupId 和 artifactId 是有约定的，不改的话，你往私服上传的 jar 命名没法看，根本分不清是哪个业务线的产物。

所以改包名这件事，本质上是把项目里所有和“若依”绑定的身份标识，换成你自己团队的命名规范。它不涉及业务逻辑改动，但涉及面特别广，从 Java 源码到 XML 映射文件，从 Maven 坐标到数据库连接，从前端 package.json 到浏览器标题栏，每一层都要覆盖到。

1.2 先列一张完整的改名清单

改名最怕的不是麻烦，而是漏改。漏改一个配置往往不会立刻报错，而是等到启动阶段或者某个功能被点开时才暴露，那时候你已经想不起来自己改过哪里了。所以我建议动手之前先建一张清单，改一项勾一项。下面这张表是我自己反复用过很多次的版本，以 RuoYi-Vue 3.8.x 为例整理：

把这张表截图存着，后面的操作都围绕它来打勾。注意我特意把“表前缀”标了“一般不动”，原因后面单独说。

2. 后端 Java 包名与 Maven 模块名改造

2.1 用 IDEA 重构改包，别手动拖目录

后端改包名最大的忌讳，是直接在系统文件管理器里把com/ruoyi目录改名，或者在 IDEA 里手动拖动 Java 文件。那样做的话，每个类的package声明和所有import语句全部失效，几百个文件的人工修改会让你改到怀疑人生。

正确姿势是用 IDEA 的 Refactor 功能。在项目树里展开com.ruoyi，右键最外层目录，选择 Refactor -> Rename，弹出对话框里填入新的包名，比如com.mycompany.erp。这里有两个关键选项必须勾上：

• Search in comments and strings：注释和字符串里的包路径才会被一起替换
• Search for text occurrences：文本中出现的包名才会被替换

这两个不勾的话，IDEA 只改 Java 文件里的声明和引用，XML、yml、properties 里写死的字符串路径全部漏掉，后续还得手工补。重构执行完，VCS 面板里会显示几百个文件变更，这是正常的，说明替换覆盖面够大。

2.2 全局搜索兜底，替换顺序有讲究

IDEA 重构再智能，也做不到 100% 覆盖所有场景。我每次重构完都会再用全局搜索扫两遍：先搜com.ruoyi，把所有剩余结果清掉，再搜单独的ruoyi字样，处理那些不以完整包路径形式出现的地方，比如日志里的 logger name、注释里的描述、pom 里的 artifactId。

这里有个替换顺序的细节值得单独说。如果你把新旧字符串混在一起全局替换，一定要先替换长的、再替换短的。具体来说就是先做com.ruoyi->com.mycompany.erp，等这一轮全部结束，再做ruoyi->erp（或者你自己的项目代号）。顺序反了的话，第一条替换会把ruoyi改成erp，然后第二条com.ruoyi的规则就匹配不上了，最后出现com.erp这种不伦不类的包路径。

另外，全程用 IDEA 的 Replace in Files 操作，不要用记事本或其他编辑器批量替换。若依源码默认 UTF-8 编码，某些编辑器保存时会悄悄改成 GBK，改完之后编译直接乱码，那个问题比包名没改干净更难查。

2.3 pom.xml、模块目录与 git 的联动修改

包名改完，接下来是 Maven 模块。父 pom.xml 里的坐标要改成自己的规范，比如：

<groupId>com.mycompany.erp</groupId> <artifactId>erp</artifactId> <version>1.0.0</version> <packaging>pom</packaging> <name>erp</name>

然后各子模块的 artifactId 同步调整，把ruoyi-admin改成erp-admin、ruoyi-system改成erp-system，以此类推。子模块的<parent>里的 groupId 和 artifactId 也要跟着变，这部分如果只替换了父 pom 没替换子 pom，Maven 刷新时会直接报坐标找不到。

模块目录名我建议也一起改，虽然 IDEA 编译不要求目录名和 artifactId 一致，但目录名不统一的话，Project 面板看起来特别别扭。在 IDEA 里对模块目录右键 Refactor -> Rename 即可，IDEA 会自动更新 modules 引用和 import 路径。如果项目已经用 git 管理，改完后看下 git status，会出现大量 delete + add 记录，这是正常的，只要目录移动后能正常编译，不需要额外处理。

改完这一轮，立刻点一下 Maven 刷新按钮，然后执行mvn clean compile验证。这里必须强调clean，因为 target 目录里旧的 class 文件不会自动消失，你只 compile 不 clean，很可能编译通过，但运行时的类还是旧的，后续排查起来全是幻觉。

3. 配置文件、Mapper 与数据库脚本同步

3.1 application.yml 里的三处必改项

包名和模块名改完，配置文件是最容易漏的一层。RuoYi-Vue 的 application.yml 里至少有三个地方要跟着动：

server: port: 8080 servlet: context-path: / spring: application: name: erp datasource: druid: url: jdbc:mysql://localhost:3306/erp_db?useUnicode=true&characterEncoding=utf8mb4&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8

第一个是spring.application.name，原来叫ruoyi，会显示在 Spring Boot 日志和监控信息里。第二个是 MyBatis 相关配置，RuoYi-Vue 一般是这样的：

mybatis: typeAliasesPackage: com.mycompany.erp.**.domain mapperLocations: classpath*:mapper/**/*Mapper.xml

typeAliasesPackage这里的写法有个细节：**.domain表示递归匹配所有子包下的 domain，如果你只写com.mycompany.erp.domain，那么 system、quartz、generator 等模块的 domain 实体类就扫不到，MyBatis 里用简单类名做别名的地方全部失效。第三个是数据源连接串里的库名，RuoYi-Vue 初始化脚本默认创建的数据库通常是ry-vue这种名字，项目名都改了，库名建议也改成自己的业务名，不然两个项目共用一套库，数据互相污染是迟早的事。

3.2 MapperScan 与 XML namespace 要一起改

RuoYi-Vue 的启动类上一般有这样的注解：

@SpringBootApplication @MapperScan("com.mycompany.erp.system.mapper") public class RuoYiApplication { public static void main(String[] args) { SpringApplication.run(RuoYiApplication.class, args); } }

@MapperScan里的包路径必须跟着新包名走。注意有些版本不止启动类一处有 MapperScan，定时任务配置类、代码生成模块的配置类里也可能有，建议全局搜一下@MapperScan，把所有出现的位置都核对一遍。

比注解更容易漏的是 Mapper XML 文件里的 namespace。RuoYi 的 Mapper 文件分散在各模块的 resources 目录下，每个文件开头都有类似这样的声明：

<mapper namespace="com.mycompany.erp.system.mapper.SysUserMapper">

这个路径如果和 Java 接口的包路径对不上，启动阶段 MyBatis 会直接报Invalid bound statement。它在 Spring 容器初始化阶段才暴露，错误信息往往被一堆启动日志淹没，新手特别容易一头雾水。我的排查经验是：启动日志里看到nested exception is org.apache.ibatis.binding.BindingException，十有八九是 namespace 没改干净。

3.3 数据库库名与代码生成器别漏掉

这里专门说下表前缀的问题。RuoYi 的表基本是sys_user、sys_role、sys_menu、sys_dept这种sys_前缀，还有 Quartz 的qrtz_前缀。改包名和项目名的时候，表前缀其实可以不动，因为表名和 Java 包名没有硬性绑定关系，你的代码里SysUser实体对应sys_user表是 MyBatis 映射决定的，跟包名不冲突。但如果你所在团队的表命名规范要求统一前缀，那就要连 SQL 初始化脚本、application.yml里的表前缀配置（如果用了全局表前缀插件）一起改，工作量会大不少，我的建议是：没有硬性要求就别动，动一次冒一次险。

代码生成器反而是个容易埋雷的地方。RuoYi 自带代码生成功能，生成新模块时有一个“生成包路径”的配置，默认值往往就是com.ruoyi。如果你只改了现有源码，没改生成器的默认配置，下次从数据库逆向生成一个新的 CRUD 模块，生成出来的代码又全是com.ruoyi，等于白改。这个配置在系统管理的代码生成页面里，也可以在 generator 模块的配置文件里改默认值。具体位置因版本而异，但思路只有一个：全局搜com.ruoyi，凡是能作为默认值出现的字符串，全部换掉。

4. 前端 Vue 的项目名称与展示文案改造

4.1 package.json、页面标题与浏览器图标

没必要等后端全部验证完再动手。前端和后端是并行的工作线，但同样需要从工程层面开始。RuoYi-Vue 前端工程默认叫ruoyi-ui，先把 package.json 改干净：

{ "name": "erp-ui", "version": "1.0.0", "description": "企业资源管理系统前端工程", ... }

注意name字段不要用中文，也不要有特殊符号，不然某些打包工具会报错。接着是浏览器标题栏，public/index.html里的<title>若依管理系统</title>改成自己的系统名。如果你用的是较新的 RuoYi 版本，标题可能还受src/settings.js里的配置控制：

export default { title: '企业资源管理系统' }

这个标题会动态覆盖浏览器标签页的文本，光改 index.html 不改 settings.js，你会发现启动后标题又变回旧的。还有public目录下的 logo 图片和 favicon，替换成自己的视觉文件，这一步虽然不影响功能，但对“去若依痕迹”的观感影响最大。

4.2 登录页、侧边栏与版权信息的视觉层修改

前端界面上的文本，比工程名更容易被忽略。RuoYi-Vue 的登录页src/views/login.vue里，系统名称、登录按钮文案、底部版权信息都是写死的。版权信息一般长这样：

<span>Copyright © 2023 RuoYi All Rights Reserved.</span>

这个字符串里的RuoYi必须换掉，否则甲方打开登录页一眼就穿帮。侧边栏顶部的标题区域，在src/layout/components/Sidebar相关组件里，用的也是 settings 里的 title。我的做法是在整个前端目录下全局搜两个关键词：RuoYi和若依，把搜索结果逐条过一遍，区分哪些是真正的界面文本、哪些是注释，界面文本全部替换成自己的系统名。

这里有一个小坑：全局搜索会把很多组件的注释里也搜出来，比如“若依框架生成”“若依通用方法”这类开发注释。这些注释不影响界面，替换与否看你是不是完美主义者。我建议至少把登录页、系统监控页面、异常页面上用户可见的文本全部清干净，开发注释可以留，但交付源码前最好也顺手处理掉，不然代码走查还是会被人挑出来。

4.3 接口前缀、跨域代理与后端端口配合

前端到后端的通路，主要在前端工程根目录的vue.config.js和.env.*文件里。RuoYi-Vue 默认的接口前缀是/prod-api，这个值一般不用改，但它必须和后端context-path或者说后端服务真实暴露的路径对得上。开发环境下vue.config.js里是这样配代理的：

proxy: { '/prod-api': { target: 'http://localhost:8080', changeOrigin: true, pathRewrite: { '^/prod-api': '' } } }

如果你把后端server.port从 8080 改成了别的端口，这里的target必须同步改，否则前端页面能打开但所有接口全部 404。如果你改了接口前缀，比如把/prod-api改成/erp-api，那么.env.development里的VUE_APP_BASE_API、vue.config.js里的 proxy key、pathRewrite规则要一起改，三处必须一致。这个一致性是前端联调最常见的坑，每次改完都先看浏览器 Network 面板里的实际请求 URL，比猜配置快得多。

5. 常见报错与排查技巧实录

5.1 编译报错：程序包不存在，根因往往是残留文件

后端mvn clean compile时如果出现“程序包 com.ruoyi.xxx 不存在”之类的错误，大概率是 IDEA 重构时漏掉了某个文件，或者有生成代码没有参与重构。先做一件事：全局搜com.ruoyi，把所有结果列出来，逐一确认。如果搜索结果是零，但编译还是报错，那就是 target 目录里的旧 class 或者旧 jar 在作怪，执行mvn clean后再编译。这一个步骤看起来简单，但确实是我见过最多人卡住的地方。

5.2 启动失败：Mapper、Bean 扫描不到的三连查

启动时报No qualifying bean of type '...SysUserMapper'，或者Bean named 'xxxService' is expected to be of type...，按顺序查三处：

1. 启动类和配置类上的@MapperScan、组件扫描包路径是否已更新
2. application.yml里typeAliasesPackage和mapperLocations是否匹配新路径
3. Mapper XML 的 namespace 是否与 Java 接口一致

这三处只要统一，99% 的扫描类问题都能解决。剩下的 1% 是缓存问题，IDEA 的缓存有时会残留旧索引，执行File -> Invalidate Caches and Restart基本能解决。

5.3 前端白屏、404 与请求路径异常

前端打开是白屏，先看浏览器 Console 和 Network。如果请求 URL 是/prod-api/...，但代理 target 指向了旧端口，改成新端口即可。如果 URL 出现了双前缀，比如/prod-api/prod-api/...，说明pathRewrite的规则没匹配上，检查vue.config.js里的 proxy 配置。如果请求全部正常但页面白屏，多半是路由或状态管理的问题，先看控制台有没有 JS 报错，再检查是不是settings.js里改了title后某个组件引用了不存在的变量。

下面这张速查表是我整理给自己团队的新人看的，直接抄过去用就行：

老实说，我给若依项目改名前后折腾过很多次，最深的体会是：别靠“记住”去改，要靠清单。每次都是先全局搜一遍旧关键词、改完立刻编译、启动、跑一遍核心接口，三步验证缺一不可。还有一个小技巧是改完以后用 IDEA 的 Find in Files 分别搜com.ruoyi和ruoyi两个关键词，如果搜索结果一个都不剩，说明改干净了；如果还剩，对着上面那张表一项一项消。这套流程走下来，换个名字大概半小时到一小时，比想起来一处改一处、最后被隐藏问题折磨一整天要省太多时间。