git切换分支后本地依赖不匹配的根源是ide缓存、构建工具状态与文件系统事件未同步。需依次执行invalidate caches and restart、清理maven本地仓库及target目录、校验jdk和gradle配置，并检查submodule与换行符一致性。
Git切换分支后本地依赖项不匹配，不是 Maven 或 Gradle 本身出错，而是 IDE 缓存、构建工具状态、文件系统事件三者没对齐。直接 mvn clean install 往往治标不治本，尤其在多模块、跨 JDK 版本、或存在 profile 切换的项目里。
IDEA 索引未重建导致“找不到类”或“依赖红标”
Git 切换分支时，物理文件已更新，但 IDEA 的 Stub Index 和 Class Index 仍按旧分支结构解析代码，结果跳转到错误类、Cannot resolve symbol 'XXX'、甚至 pom.xml 里明明有依赖却标红。
- 不要只点右上角刷新按钮——它只触发 Maven/Gradle 同步，不重建索引
- 必须执行 File → Invalidate Caches and Restart… → Invalidate and Restart（不是 Just Restart）
- 重启后等待右下角 “Indexing…” 消失再操作，否则仍会误判
- 若项目含大量 Lombok 或 Kotlin，建议勾选 “Clear file system cache and Local History” 一并清理
Maven 本地仓库未隔离导致版本污染
不同分支可能声明了冲突的依赖版本（比如 spring-boot-starter-web v2.7.x vs v3.2.x），而 Maven 默认共用全局 ~/.m2/repository。切换分支后，IDEA 可能仍加载旧版本的 jar 中的 class 文件，引发 NoSuchMethodError 或编译通过但运行失败。
- 检查当前分支的
pom.xml是否启用<dependencymanagement></dependencymanagement>锁定版本，缺失时极易出问题 - 避免仅靠
mvn clean install：它只更新本地安装的 artifact，不清理 IDE 已加载的类路径 - 稳妥做法是：
mvn clean→ 关闭 IDEA → 手动删掉target/和.idea/libraries/下对应模块的 xml 文件 → 再打开项目重新 import - 长期建议：为不同分支设置独立
-Dmaven.repo.local=repo-feature-a，但需配合 CI 脚本统一管理
Gradle 构建缓存与配置未随分支重载
Gradle 的 buildSrc、settings.gradle 或 gradle.properties 可能在不同分支中差异较大，但 IDEA 默认复用上次导入的模型。表现为 Could not find artifact、插件类找不到、甚至 build.gradle 语法高亮异常。
- 不要只点 “Reload project” —— 它跳过
settings.gradle重解析 - 正确流程：File → Project Structure → Project → Project SDK / Language level 先确认是否匹配当前分支要求（如分支用 JDK 17，但 IDE 仍设为 JDK 8）
- 然后右键项目根目录 → Reload project，而非点击工具栏的 Gradle 刷新图标
- 若使用
includeBuild或 composite build，务必检查settings.gradle中路径是否随分支变更失效（例如子项目被移除但引用仍在）
Git submodule 或 patch 差异引发二进制不兼容
某些分支启用了 submodule，或打了本地 patch（如修改第三方库源码），而切换后这些改动未同步生效，导致编译时类签名不一致、ClassCastException 或 VerifyError。
- 执行
git submodule status，确认所有 submodule 处于当前分支期望的 commit - 若存在本地 patch，切分支前应先
git stash；切完后git stash pop并手动验证是否仍适用 - 检查
.gitattributes是否设置了eol=lf或core.autocrlf，换行符差异会导致 jar 内部 class 文件哈希变化，Maven 认为依赖已损坏 - 遇到
Dependency convergence error，优先跑mvn dependency:tree -Dverbose定位冲突源头，而非盲目 exclude
真正麻烦的从来不是“哪个命令能跑通”，而是哪一层缓存没清、哪个路径没对齐、哪处隐式状态还在生效。每次切换分支后花 30 秒检查 git status、mvn help:effective-pom | grep version、IDE 右下角的 SDK 和 Build Tool 配置，比反复重启和重装快得多。
