子模块重命名后必须同步更新settings.gradle的include路径及所有project()依赖声明，否则Gradle静默跳过模块或构建失败；还需清理IDE缓存并重载项目。
settings.gradle 中的 include 路径必须同步更新
子模块重命名后，settings.gradle 里所有 include 语句中的路径字符串必须严格匹配新目录名。Gradle 不会自动映射旧名到新名，也不会报“目录不存在”这种直观错误——它可能静默跳过该模块，导致后续构建失败或依赖解析为空。
常见错误现象：
-
include ':app'但实际目录已改名为myapp→ Gradle 找不到myapp/build.gradle，却仍尝试执行:app:compileJava，报错Project directory not part of the build - 用
include ':feature:login'声明，但目录结构是feature/login-module→ 必须改为include ':feature:login-module'，不能省略末级名称
关键点：冒号 : 是路径分隔符，不是文件系统分隔符；include 参数是逻辑路径，不是物理路径。只要目录名变了，逻辑路径就必须变。
所有 project(':xxx') 依赖声明要逐个替换
任何子项目中使用 implementation project(':old-name')、api project(':lib:utils') 这类写法的地方，都必须手动搜索并替换成新路径。IDE（如 IntelliJ）通常不会自动更新这些字符串，因为它们是纯字符串字面量，不是符号引用。
容易踩的坑：
- 只改了
settings.gradle，忘了改build.gradle里的project()—— 编译时提示Could not find project ':old-name' - 在 Kotlin DSL 的
settings.gradle.kts中用了include("old-name")，但没同步改build.gradle.kts里的project(":old-name") - CI 脚本或自定义 Task 里硬编码了项目路径（比如
gradle.includedBuilds.find { it.name == 'old-name' }），也会失效
buildSrc 或插件中硬编码的项目名需检查
如果项目用了 buildSrc 或自定义 Gradle 插件，并在里面通过 project.rootProject.findProject(':old-name')、project(':old-name').extensions.findByType(...) 等方式访问子项目，这些调用全部会失败。
这类代码往往藏得深，且不报编译错误，只在构建执行期抛 NullPointerException 或返回 null。建议全局搜索 ':old-name' 和 'old-name'（带单引号的字符串），尤其注意 Groovy/Kotlin 的字符串拼接场景，比如 ":${name}-core"。
IDE 同步与缓存问题常被忽略
即使所有配置都改对了，Android Studio 或 IntelliJ 仍可能沿用旧的项目索引，表现为：模块显示为灰色、依赖无法跳转、gradle projects 列表里看不到新模块。
必须执行的操作：
- 点击菜单 File → Reload project（不是 Sync Project with Gradle Files）
- 删掉
.idea/modules/下对应旧名的.iml文件 - 清除 Gradle 缓存：
./gradlew --stop && rm -rf ~/.gradle/caches/（Linux/macOS）或gradlew --stop && rd /s/q "%USERPROFILE%\.gradle\caches"（Windows）
最麻烦的是：某些旧版 Android Studio（如 Giraffe 及更早）会在后台偷偷缓存 settings.gradle 解析结果，改完不重启 IDE 就无效。
