1. 项目背景与需求分析在接手一个基于RuoYi-Vue框架的二次开发项目时我们经常遇到需要修改默认包名、模块名和项目名称的情况。这可能是由于企业命名规范要求或是为了避免与原始框架产生冲突。RuoYi-Vue作为一款基于Spring Boot和Vue.js的前后端分离快速开发框架其默认的包结构为com.ruoyi但实际业务中我们可能需要将其改为公司专属域名如com.company.project。重要提示修改包名不是简单的全局替换操作需要特别注意前后端联调配置、Maven依赖管理和Vue组件注册等关键环节。2. 完整修改流程详解2.1 后端包名修改步骤IDE重构操作IntelliJ IDEA为例右键项目根目录 → Refactor → Rename修改顶层包名com.ruoyi为目标名称如com.techdemos勾选Search in comments and strings和Search for text occurrences关键配置文件更新!-- pom.xml需要修改的配置 -- groupIdcom.techdemos/groupId artifactIdruoyi-module/artifactId !-- application.yml中的包扫描路径 -- mybatis: mapperLocations: classpath*:com/techdemos/**/mapper/*.xml特殊文件处理RuoYiApplication.java需要重命名并更新MapperScan注解检查所有ComponentScan注解的basePackages属性更新Swagger配置中的basePackage设置2.2 前端模块名修改方案Vue项目基础配置变更// package.json { name: techdemos-admin, dependencies: { techdemos/ruoyi-ui: 1.0.0 } }Webpack相关配置调整// vue.config.js module.exports { publicPath: process.env.NODE_ENV production ? /techdemos/ : /, outputDir: techdemos-dist }路由与API配置更新// src/utils/request.js const service axios.create({ baseURL: process.env.VUE_APP_BASE_API /techdemos-api })3. 常见问题与深度解决方案3.1 修改后启动报错排查指南ClassNotFoundException场景检查target/classes目录下编译后的包结构清理Maven缓存并重新编译mvn clean install -U确认IDE的Build → Rebuild Project操作Vue组件注册失败处理// 原组件路径报错时检查 import Layout from /techdemos/views/layout // 需要同步更新vue-router配置MyBatis映射文件加载异常# 确保yml配置与实际路径匹配 mybatis: mapperLocations: classpath*:com/techdemos/**/mapper/xml/*.xml3.2 多模块项目同步修改技巧对于包含ruoyi-admin、ruoyi-system等子模块的项目父POM统一管理modules moduletechdemos-admin/module moduletechdemos-system/module /modules依赖关系重构!-- 子模块间引用需更新 -- dependency groupIdcom.techdemos/groupId artifactIdtechdemos-common/artifactId /dependency前端多模块适配// 使用lerna管理多package { packages: [packages/techdemos-*] }4. 高级配置与自动化方案4.1 使用Maven插件批量处理plugin groupIdcom.coderplus.maven.plugins/groupId artifactIdcopy-rename-maven-plugin/artifactId executions execution phasegenerate-sources/phase goals goalrename/goal /goals configuration sourceFilesrc/main/java/com/ruoyi/sourceFile destinationFilesrc/main/java/com/techdemos/destinationFile /configuration /execution /executions /plugin4.2 前端自动化脚本方案// renameScript.js const fs require(fs); const path require(path); const replaceInFile (filePath, oldStr, newStr) { let content fs.readFileSync(filePath, utf8); content content.replace(new RegExp(oldStr, g), newStr); fs.writeFileSync(filePath, content); }; // 批量处理vue文件中的组件引用 const processVueFiles (dir) { fs.readdirSync(dir).forEach(file { const fullPath path.join(dir, file); if (fs.statSync(fullPath).isDirectory()) { processVueFiles(fullPath); } else if (fullPath.endsWith(.vue) || fullPath.endsWith(.js)) { replaceInFile(fullPath, /ruoyi, /techdemos); } }); };4.3 数据库相关修改要点SQL脚本更新-- 原ruoyi相关表名前缀修改 RENAME TABLE ry_user TO td_user;MyBatis动态表名处理TableName(value td_user) public class User extends BaseEntity { // 实体类定义 }Redis缓存键前缀更新# application.yml redis: keyPrefix: techdemos:5. 部署与持续集成适配5.1 Docker容器化配置调整# 后端Dockerfile示例 FROM openjdk:8-jdk COPY target/techdemos-admin.jar /app.jar ENTRYPOINT [java,-jar,/app.jar,--spring.profiles.activeprod]5.2 Nginx代理配置更新server { listen 80; server_name techdemos.example.com; location /techdemos-api/ { proxy_pass http://backend-server/; } location /techdemos/ { alias /var/www/techdemos-dist/; try_files $uri $uri/ /techdemos/index.html; } }5.3 Jenkins流水线改造pipeline { environment { ARTIFACT_NAME techdemos-admin } stages { stage(Build) { steps { sh mvn clean package -DskipTests sh npm run build --prefix frontend } } } }6. 验证与回归测试要点后端核心检查清单启动日志中的包扫描路径是否正确Swagger接口文档的basePackage是否更新MyBatis的mapper.xml文件加载情况前端关键验证项// 检查所有API请求路径 axios.get(/techdemos-api/system/user/list) // 验证静态资源加载路径 img src/techdemos/static/logo.png集成测试特别注意检查所有跨模块的Feign调用接口验证OAuth2等安全配置中的路径白名单测试文件上传下载等涉及物理路径的功能我在实际企业级项目改造中发现最容易被忽视的是日志配置中的包名过滤和AOP切面表达式。建议在修改完成后专门检查logback-spring.xml中如下配置logger namecom.techdemos levelDEBUG/以及Spring AOP的切点定义Pointcut(execution(* com.techdemos..*.*(..))) public void techdemosPointcut() {}这些细节往往在项目启动时不会立即暴露问题但在运行时会导致日志缺失或切面失效等隐蔽性问题。建议建立完整的检查清单在修改后逐项验证。