1. 先把四层命名关系理清不然改一个炸三个IntelliJ IDEA 里的改名之所以让很多人头疼根本原因在于项目根目录名、项目名、模块名、包名是四套独立的命名体系它们在磁盘、IDE 配置、构建脚本里各存一份彼此有关联但又不完全同步。你改了其中一个另外三个不会自动跟着变于是就出现了明明改完了一编译全红的场面。我最初接触这套东西的时候也踩过把文件夹名直接右键重命名结果 IDEA 打开后一堆模块路径失效的坑。后来做的项目多了尤其是多模块的 Maven、Gradle 工程才慢慢把这几层关系摸清楚。这一节我把它们摊开讲后面所有操作都建立在这个认知上。1.1 根目录名、项目名、模块名、包名各自存在哪里先看一张对照表这张表我建议你直接收藏改名前对着看一遍能省掉一大半排查时间。名称层级物理位置/载体谁在读取它改了会影响什么项目根目录名磁盘上的文件夹名操作系统、Git、构建工具的工作目录所有绝对路径引用、CI 脚本、IDE 最近项目记录项目名.idea/.name文件或pom.xml的name、settings.gradle的rootProject.nameIDEA 标题栏、构建产物名打包出的 jar/war 名称、IDEA 显示名模块名.idea/modules.xml、各模块的.iml文件、pom.xml的artifactIdIDEA 模块树、模块间依赖模块间依赖解析、聚合构建顺序包名源码目录结构 package声明 import语句编译器、JVM、框架扫描类加载、Spring 扫描、MyBatis 映射、序列化类名这四层里包名是最硬的。因为它同时存在于文件系统的目录结构和 Java 源码的声明里两边必须严格一致差一个字符编译器就报错。而项目根目录名是最软的它本质上只是个文件夹名改它不影响代码逻辑但会影响所有写死了路径的脚本。项目名和模块名处在中间它们由 IDE 配置文件管理改错了 IDEA 会提示模块找不到但代码本身还能编译。理解了这个软硬程度的梯度你就能判断改名的风险等级根目录名 项目名 ≈ 模块名 包名。1.2 一次改名会牵动哪些文件影响范围清单很多人改名的思路是哪里报错改哪里这在单模块小项目里能蒙混过关但在中大型工程里会陷入无限循环。正确的做法是先列清单一次性改完。以我经手过的一个 Spring Boot 多模块项目为例把一个叫my-shop-service的模块改成order-service实际被牵动的位置有磁盘目录my-shop-service/这个文件夹该模块的pom.xmlartifactId和name父pom.xmlmodules里的子模块声明依赖它的兄弟模块pom.xmldependency里的artifactId.idea/modules.xml模块文件路径.idea/compiler.xml模块编译输出路径各模块下的.iml文件如果没走外部存储settings.gradleGradle 工程运行配置里的模块选择Dockerfile、Jenkinsfile、部署脚本里写死的 jar 名Nginx 或网关配置里的服务名如果服务名跟模块名一致注意IntelliJ IDEA 从 2017.3 之后默认把.iml文件存到.idea/modules/下而不是模块目录里但你如果手动改过设置或者工程是从老版本升上来的模块目录里可能还留着.iml。改名前先在项目根搜一遍*.iml心里有个数。把这些列出来之后你会发现改名字这件事的本质是同步多个副本。任何一个副本没同步就会在某个环节爆出来。我后面每一节讲的实操其实都是围绕如何不漏副本展开的。2. 动手前的准备三件必须做的事直接改名然后祈祷不出问题是新手最容易掉进去的坑。我在真实项目里养成了一套固定流程改名前花五分钟做三件事能避免九成以上的返工。2.1 建立可回退的基线第一件事保证你能一键回到改名前。如果你用的是 Git最省事的办法是在改名之前先提交一次或者新建一个分支git status git add -A git commit -m chore: 改名前的稳定基线 git checkout -b rename/order-service这样即使改炸了git checkout main或者git reset --hard就能回来。为什么要单独开分支因为改名会产生大量文件移动记录混在功能分支里代码评审的人根本看不出你改了什么。单独一个分支评审范围清晰回滚也干净。如果你这个项目没有版本控制我确实见过一些内部小工具项目是裸目录那就手动复制整个项目文件夹在副本上操作。别嫌占硬盘一个能回退的副本值这个钱。2.2 关掉占用与清掉缓存第二件事彻底关闭 IDEA 和所有 Java 进程。Windows 下文件夹被占用是最常见的改名失败原因表现是重命名时提示文件夹正在使用中。哪怕 IDEA 界面关了后台的 Gradle Daemon、Maven 进程、热部署的进程可能还活着。Windows 上可以用任务管理器结束所有java.exe。Linux/macOS 上ps -ef | grep -i java # 找到残留进程后 kill -9 pid关掉之后顺手删掉构建产物和缓存目录让下次打开是干净状态rm -rf target/ build/ out/ rm -rf .idea/ # 谨慎这会丢掉运行配置和代码风格设置.idea目录要不要删看你的取舍。删掉它 IDEE 会重新生成模块关系会重新扫描能规避很多陈旧的路径配置代价是你自建的运行配置、代码检查模板、颜色主题设置会丢。我的习惯是先备份.idea再删出了问题还能对照着把运行配置抄回来。2.3 生成一份改名影响清单可直接抄第三件事用全局搜索把写死的旧名字全找出来。IDEA 的CtrlShiftFmacOS 是CmdShiftF是全项目搜索记得把搜索范围从当前文件切到整个项目并在选项里勾上包含非源码文件否则Dockerfile、Jenkinsfile这类文件会被漏掉。搜索的时候建议按顺序搜这几个关键词旧的模块名或项目名比如my-shop-service旧的包路径字符串比如com.myshop.old旧的项目根目录名比如my-shop-parent大小写变体比如myshop、MyShop——这一点特别容易被忽略配置文件里经常用下划线或驼峰的其他写法搜出来的结果先别急着改把文件路径记下来按源码 / 构建脚本 / IDE 配置 / 部署脚本分类。分类完了你会发现改动量其实没有想象中大而且能确定一个安全的执行顺序。提示搜索结果里的.idea/workspace.xml会包含大量历史记录比如最近打开的文件路径、运行配置里的工作目录。这个文件属于 IDE 自动生成通常不需要手动改直接删掉让 IDEA 重建反而更快。3. 改项目根目录名磁盘文件夹级别的重命名这是我们常说的改项目根目录名称本质上就是把项目最外层那个文件夹换掉名字。这一步风险最低但很多人第一步就做错了——在 IDEA 里开着项目改文件夹或者改完不知道要重新导入。3.1 关闭 IDEA 再改文件夹名操作本身很简单确认 IDEA 已关闭后在文件管理器里直接重命名文件夹即可。不过有两个细节值得说第一Windows 下改大小写要绕一步。Windows 的文件系统默认不区分大小写你想把myshop改成MyShop直接改可能会提示目标名称已存在。解决办法是先改成一个中间名再改成目标名mv myshop myshop_tmp mv myshop_tmp MyShop第二改完名字后原来 IDEA 的最近项目列表里那条记录会失效。你会发现点进去提示路径不存在这不是项目坏了只是记录指向的旧路径没了。不用管这条记录重新用Open打开新路径的文件夹就行。3.2 重新导入项目并修正绑定关系重新打开项目时IDEA 会问你这个项目要不要按 Maven/Gradle 工程导入。这里有个经验如果原来的.idea目录还在IDEA 可能会沿用旧的模块路径导致模块树里一片灰。我一般的处理方式是打开新路径的文件夹如果 IDEA 提示检测到 Maven/Gradle 项目选择自动导入导入完成后看右侧 Maven 面板或 Gradle 面板确认模块都识别到了如果模块没识别右键pom.xml选Add as Maven ProjectGradle 是Link Gradle Project命令行能验证的东西就别靠眼睛。导入之后跑一次构建mvn clean compile # 或者 ./gradlew clean build构建通过才算改名成功了一半剩下的一半是 IDE 的索引和运行配置。3.3 顺手清理的残留文件重新导入之后有几个地方值得顺手检查一下。项目根目录下可能残留着旧名字命名的构建产物比如my-shop-parent-1.0.jar这是 Maven 的finalName默认取了 artifactId 的结果。如果你的部署脚本里写死了这个 jar 名那就得同步改。另外target/或build/目录在切换根目录名之后建议清一次。因为 IDE 的编译输出路径可能还记着旧路径不清的话偶尔会出现改了代码不生效的诡异现象。IDEA 里的清理入口是Build Rebuild Project或者直接用命令行mvn clean。还有一个容易被忘记的地方绝对路径的配置文件。有些团队的application.yml里会写日志输出路径、文件上传路径里面带着项目根目录名。这类改动搜索不易发现建议改名后专门 grep 一遍file:、path:、/home/、D:\这类关键词。4. 改项目名让 IDEA 标题栏和构建脚本都认新名字项目名和根目录名经常被混为一谈但它们其实是两个东西。你把文件夹改成order-platformIDEA 标题栏上可能还显示着my-shop-parent因为项目名的真正来源是.idea/.name或者构建脚本。4.1 IDEA 内置的项目重命名入口IDEA 提供了项目级的重命名功能入口在项目树最顶层的节点上右键选择Refactor Rename或者直接用ShiftF6。改完之后 IDEA 会更新.idea/.name文件的内容同时标题栏立刻变成新名字。这里要注意一个历史遗留问题IDEA 不同版本对项目名的处理不太一致。有些版本会同步改掉.idea/modules.xml里的路径有些版本只改显示名。所以我习惯改完之后再手动确认一下.idea/.name里的内容对不对cat .idea/.name如果这个文件里是空白的或者内容怪异直接手动写上新项目名保存后重启 IDEA 即可。这个文件就是个纯文本一行内容没有格式要求。4.2 Maven 与 Gradle 工程里的项目名IDEA 的项目名和构建工具的项目名可以不一致但强烈建议保持一致否则团队里其他人拉下代码打开会看到两个名字非常混乱。Maven 工程里pom.xml顶部的这几行决定构建工具视角下的项目名groupIdcom.example.order/groupId artifactIdorder-platform/artifactId version1.0.0-SNAPSHOT/version nameorder-platform/name description订单平台主工程/description其中artifactId是关键的它决定了打包产物的默认名字order-platform-1.0.0-SNAPSHOT.jar也被子模块引用来定位父工程。name只是给人看的描述性名字通常跟 artifactId 一致。Gradle 工程对应的位置是settings.gradlerootProject.name order-platform include order-service include order-common改rootProject.name之后执行./gradlew projects就能看到新名字生效了。注意artifactId和groupId一旦改掉会直接影响依赖它的其他工程。如果这个工程被别的系统以 Maven 坐标的形式引用那你就得跟对方同步否则他们的构建会失败。这是改项目名最容易被低估的连带影响。4.3 版本控制与外部引用同步项目名改完之后还有几个外部位置需要检查。CI 流水线里通常有一个项目路径或工作目录的配置项如果配的是绝对路径就得改配的是相对路径或者通过环境变量注入一般不用动。代码托管平台上的仓库名是另一回事它跟本地项目名没有强绑定关系。但为了团队沟通方便我一般会建议仓库名和项目名对齐避免出现仓库叫 shop项目叫 order-platform模块叫 order-service这种三层全不一样的情况。还有一个细节IDEA 的.idea/vcs.xml里可能记录了版本控制映射关系如果只是改名字不改目录结构这个文件通常不需要动。真正需要关注的是.git/config里的远程地址改仓库名之后记得同步更新git remote -v git remote set-url origin 新的仓库地址5. 改模块名多模块工程最容易翻车的一步模块重命名是整套操作里出错概率最高的。单模块项目改起来还好多模块项目里模块名同时出现在自己的pom.xml、父pom.xml的modules列表、以及依赖它的其他模块的dependency里三处必须同时改。5.1 单模块工程的模块重命名流程单模块项目里模块名通常等于项目名改起来比较直接。IDEA 的入口是File Project Structure快捷键CtrlAltShiftS在左侧选Modules选中模块后点上面的重命名图标或者直接在模块上右键Refactor Rename。改完之后 IDEA 会自动更新.idea/modules.xml。你可以打开这个文件确认一下project version4 component nameProjectModuleManager modules module fileurlfile://$PROJECT_DIR$/.idea/modules/order-service.iml filepath$PROJECT_DIR$/.idea/modules/order-service.iml / /modules /component /project如果这里的路径和实际文件对不上模块树就会显示成灰色右键也没有任何菜单。这种情况的处理办法是删掉这行记录然后重新用 Maven/Gradle 面板导入模块。5.2 多模块聚合工程目录、pom、settings.gradle 三处对齐多模块工程里模块名对应三个位置我用一个具体例子说明。假设原本结构是这样my-shop-parent/ ├── pom.xml (父工程) ├── my-shop-common/ │ └── pom.xml ├── my-shop-service/ │ └── pom.xml └── my-shop-web/ └── pom.xml现在要把my-shop-service改名成order-service涉及以下改动第一步改磁盘目录名。关掉 IDEA把my-shop-service/改名为order-service/。第二步改这个模块自己的pom.xml。artifactIdorder-service/artifactId nameorder-service/name parent groupIdcom.example.order/groupId artifactIdmy-shop-parent/artifactId version1.0.0-SNAPSHOT/version /parent第三步改父pom.xml的模块声明。modules modulemy-shop-common/module moduleorder-service/module modulemy-shop-web/module /modules第四步改依赖它的模块。比如my-shop-web依赖了原来的my-shop-servicedependency groupIdcom.example.order/groupId artifactIdorder-service/artifactId version1.0.0-SNAPSHOT/version /dependency如果你用的是 Gradle第二步和第三步合并到settings.gradle里include order-common include order-service include order-web同时模块目录下的build.gradle基本不用改名字除非里面写了archivesBaseName或者rootProject.name这类字段。提示改多模块的模块名我建议用mvn -pl order-service -am clean install这种方式单独验证被改的模块能不能编译比整个工程重新构建快得多定位问题也精准。5.3 模块改名后的依赖引用修复模块改完之后IDEA 的模块依赖关系需要重建。常见的现象是编译命令行能过但 IDEA 里代码全是红的因为 IDE 的模块依赖缓存还是旧的。处理步骤我一般是这样的右键项目根pom.xml选Maven Reload ProjectGradle 是Reload Gradle Project如果还不行File Invalidate Caches勾选Clear file system cache and Local History重启重启后再看Project Structure Modules确认依赖关系里有新模块名另外有个细节模块改名后运行配置里的模块选择会失效。IDEA 会在运行配置上标红提示找不到模块。这时候进Run Edit Configurations把Use classpath of module重新选一遍就行。这个坑我在第一次改多模块名字的时候卡了半小时一直以为是依赖没导进来其实是运行配置没更新。6. 改包目录名最需要谨慎的一层包名修改是四层里唯一会真正影响代码正确性的操作。原因很简单Java 的包名和目录结构是强绑定的com.example.old这个包必须放在com/example/old/目录下而且每个类的第一行package声明必须一模一样。6.1 包名不是文件夹名二者必须同源先说一个初学者最容易搞混的点src/main/java/com/example/old/这个路径中com/example/old是包路径而com、example、old这三个目录本身只是文件夹。IDEA 能不能把某个文件夹识别成包取决于它有没有被标记为 Sources Root源码根目录也就是那个蓝色的小方块图标。如果目录不是蓝色的你右键重命名时看到的是Rename directory如果是蓝色的看到的是Rename package。这两个操作的差别很大——前者只改文件夹名后者会连带更新所有package声明和import语句。看到Rename directory的时候一定要停下来想一想是不是这个目录没有被正确标记。还有一种情况是包名和目录本身就不一致比如目录叫com/example/old但类里写的是package com.example.legacy;。这种在 IDEA 里通常表现为整个文件满屏红色或者顶部有黄色波浪线提示。这种工程本身就有问题改名前建议先修复一致性。6.2 用重构功能改包名的完整流程标准做法是用 IDEA 的 Rename Package 功能。操作流程在项目视图里选中要改的包比如com.example.old按ShiftF6或者右键Refactor Rename在弹出的对话框里选择Rename package而不是Rename directory输入新包名比如com.example.order点Refactor之前先点Preview看一眼会改哪些文件强烈建议先点 Preview。尤其是老项目包名可能被字符串形式写在了 XML 配置、properties 文件、甚至 SQL 脚本里。Preview 面板会列出所有将被修改的位置你可以在里面逐个确认把不该改的取消勾选。IDEA 的重构对话框里有两个勾选项值得注意Search in comments and strings会把注释和字符串常量里的旧包名也改掉。大多数情况下该勾上但如果某段字符串是日志格式或者对外协议的一部分改了可能引发兼容问题需要甄别。Search for text occurrences范围更广会扫描非 Java 文件。改包名的时候建议勾上因为 Spring 的component-scan、MyBatis 的type-aliases-package都可能写着旧包名。6.3 手动改包名时的排查清单有些场景下 IDEA 的重构不适用比如包名只出现在配置文件里、或者工程结构太乱导致重构误伤。这时候就得手动改手动改的清单如下检查位置典型写法不改的后果Java 源码package声明package com.example.old;直接编译报错Java 源码import语句import com.example.old.Foo;编译报错或引用错类Spring 扫描配置ComponentScan(com.example.old)启动时 Bean 找不到Spring Boot 启动类位置类所在包决定默认扫描范围扫描范围变化Bean 注入失败MyBatis 别名包type-aliases-packagecom.example.old.entityMapper XML 里的短类名解析失败MyBatis Mapper 命名空间namespacecom.example.old.mapper.UserMapper启动报 Mapper 绑定异常日志配置logger namecom.example.old levelDEBUG/日志级别配置失效序列化相关类的全限定名写入文件或消息队列反序列化时 ClassNotFound运行配置主类全限定名启动时提示找不到主类测试代码测试类的包路径与主类对应无法访问包级私有成员这里面我最想强调的是序列化。如果你的类被写进了 Redis、Kafka 消息或者本地文件全限定类是数据的一部分。改包名之后旧数据反序列化会直接失败。这种情况要么保留旧包做兼容类要么在数据层面做迁移。这是文档里很少提但生产环境真实会踩的坑。还有一个高频问题Spring Boot 的默认组件扫描范围取决于启动类所在的包。比如启动类原本在com.example.old扫描范围是com.example.old.**你把它挪到com.example.order之后如果有些类还留在com.example.old包下它们就不会被扫描到了启动时表现为一堆NoSuchBeanDefinitionException。解决办法是显式加ComponentScan(basePackages {com.example.order, com.example.old})做过渡或者干脆把类全挪过去。7. 高频故障速查与排查思路改名过程中遇到的问题八成集中在下面这几种。我按现象—原因—解决整理成速查表遇到问题可以直接对号入座。7.1 编译过了运行报 ClassNotFoundException这是改名之后最典型的症状。命令行mvn clean compile通过但一运行就报某个类找不到或者报ClassNotFoundException、NoClassDefFoundError。原因通常是运行时的 classpath 还指向旧的输出目录。IDEA 的运行配置里记录了模块的 classpath模块改名后这个映射没更新。排查路径打开Run Edit Configurations检查Use classpath of module这一项看是不是标红或者指向了不存在的模块重新选择当前模块保存后重跑如果运行配置没问题那再看Project Structure Modules Paths确认Output path和Test output path指向的目录是存在的。改名之后这些路径有可能还写着旧的模块名导致编译产物输出到了一个已经不存在的目录。还有一种更隐蔽的情况多模块工程里依赖模块的 jar 没有重新安装到本地仓库。比如order-web依赖order-service你改了order-service的 artifactId但本地仓库里还是旧的坐标IDEA 从仓库拿到的是旧版本。解决方法是先mvn clean install被依赖的模块。7.2 Git 把改名识别成删除加新增改完名字提交git status一看一堆deleted加一堆untrackedgit log里的文件历史断掉了。这是 Git 的正常行为——它本身不记录重命名这个动作只是在 diff 时做相似度推断。想保留文件历史有两个办法用git mv来改文件名而不是先删后加git mv old-directory new-directory如果已经改完了用git add -A让 Git 在暂存阶段做重命名检测git add -A git status # 此时通常显示为 renamed如果文件内容改动超过一定比例Git 可能还是会认为这是新文件。这个阈值可以通过git diff -M或-C参数调整。不过在大多数场景下只要文件内容改动不大git add -A之后提交记录里会正确显示为 rename。注意跨大小写的重命名在 Windows 上特别容易出问题。因为 NTFS 默认不区分大小写Git 有时识别不到变化需要先把文件改成一个完全不同的名字提交再改成目标名字。我在Foo.java改成foo.java的时候踩过这个坑最后是分两次提交解决的。7.3 改了没生效缓存与索引的三处开关改完名字重启 IDEA发现还是显示旧名字或者搜索还搜得到旧路径。这类改了没生效的问题几乎都是缓存导致的。文件系统缓存File Invalidate Caches勾选清除文件系统缓存重启 IDEAMaven/Gradle 索引右侧工具面板点刷新按钮或者命令行mvn -U clean install强制更新浏览器或运行时的临时目录如果是 Web 项目out/或者target/里的旧 class 文件没清干净JVM 加载的还是旧的我个人的经验是改名操作完成后第一件事就是 Rebuild Project第二件事是 Invalidate Caches第三件事是重新跑一遍完整构建。这三步做完百分之九十五的没生效问题都会消失。还有一种非常少见的情况是操作系统层面的路径缓存。Windows 上偶尔会出现文件夹改名后资源管理器打开还是旧名字的情况按 F5 刷新或者重启资源管理器就好了跟 IDEA 没关系。8. 实操心得几条踩过坑才明白的经验前面讲了具体操作这一节我聊几个不写在文档里但真有用的经验。8.1 改名顺序与提交节奏改名的顺序我的建议是从外到内从软到硬先改根目录名再改项目名再改模块名最后改包名。原因是这样每一层的改动都能独立验证出问题定位范围小。提交节奏上不要把所有改名塞进一个 commit。我会拆成至少三个提交refactor: 重命名项目根目录与项目名refactor: 重命名 order-service 模块及其依赖引用refactor: 包名从 com.example.old 迁移到 com.example.order这样做的好处是代码评审时每一部分改动都可读出了问题也能精确回滚。相反一个几千行的巨型 commit评审的人只会点通过等于没评审。8.2 团队协作中的改名约定如果是团队项目改名前一定要先沟通。我见过有人周末自己把模块名全改了周一所有人拉代码后全线飘红光修 IDE 配置就花了一上午。一个比较好落地的约定是改名操作单独开分支不和其他功能混在一起在分支上做完整验证构建、启动、跑通核心流程后再合并合并后在群里通知附带一句拉取后请执行 Reload Project 和 Rebuild如果包名涉及序列化数据提前评估是否需要数据迁移窗口对于跨团队共享的模块改 artifactId 属于破坏性变更需要走版本号升级流程比如从1.0.0升到2.0.0并在变更说明里明确写清楚坐标变化让对方有准备时间。8.3 一份可以贴在显示器边的执行清单最后把我自己用的改名清单贴出来每次改名对着走一遍基本不会漏。准备阶段提交或复制一份可回退的基线关闭 IDEA 与所有 Java 进程全局搜索旧名字记录涉及的文件确认.idea目录是否备份根目录改名文件管理器重命名注意大小写的两步法重新打开项目确认模块识别正常命令行执行一次完整构建项目名与模块名改名改.idea/.name改pom.xml的 artifactId / name 或settings.gradle的 rootProject.name改父工程的 modules 列表改依赖方的 dependency 声明Reload Project检查模块树更新运行配置的模块选择包名改名确认目录被标记为 Sources Root用 Rename Package 并 Preview检查 Spring 扫描、MyBatis 别名包与命名空间检查日志配置与运行配置里的主类检查是否有序列化数据受影响收尾Rebuild ProjectInvalidate Caches 并重启跑完整构建 启动 冒烟测试分开提交写清楚每步改了什么我在实际使用中发现绝大多数改名后工程起不来的问题都不是代码本身的问题而是某个配置副本没同步。所以与其在出问题后靠经验猜不如改之前把清单列全一次改干净。另外一个小技巧如果你的项目结构比较复杂改完名字之后用tree或find命令把目录结构导出一份和改名前的对比一下能一眼看出哪些目录没改到位。