分支切换失败主因是工作状态不满足安全条件，分为四类：未提交修改冲突、本地分支不存在、index.lock残留阻塞、IDE/容器环境导致状态错位。
分支切换失败不是 Git 坏了，而是它在明确告诉你：当前工作状态不满足安全切换条件。 大多数报错都能归为四类：未提交修改冲突、本地分支不存在、index.lock 阻塞、或 IDE/容器环境导致的状态错位。下面按真实排查顺序展开。
未提交修改阻止 checkout
这是最常遇到的提示，典型错误是：error: Your local changes to the following files would be overwritten by checkout 或 untracked working tree files would be overwritten。Git 不会覆盖你没保存的改动，哪怕只是新建了一个 .env 文件。
- 用
git status确认是modified还是untracked—— 两者处理方式不同 - 如果只是临时切换、不想提交，优先用
git stash -u（-u包含 untracked 文件） - 如果文件本就不该进版本库（如 IDE 配置、构建产物），先加进
.gitignore，再用git clean -fd清理（注意：不可逆） - 别直接删文件再切分支 ——
git checkout -f强制覆盖只对已跟踪文件生效，对 untracked 文件无效
本地没有该分支，但远程有
执行 git checkout main 报 error: pathspec 'main' did not match any file(s) known to git，说明 refs/heads/main 在本地根本不存在。常见于老仓库克隆后远程默认分支已从 master 改为 main，但本地没同步。
覆盖A股热点发现、可比公司分析、基金诊断筛选、资金流向分析、多维选股、行情技术分析、股东股本分析及深度技术分析全流程，为投资顾问提供全方位市场分析参考。
- 先运行
git ls-remote --heads origin确认远程是否存在main - 若存在，用
git fetch origin main:refs/remotes/origin/main拉取远程追踪分支 - 再执行
git checkout main（Git 2.23+ 会自动创建本地分支并设置 upstream） - 或者一步到位：
git switch -c main --track origin/main（比checkout更语义化）
index.lock 文件残留导致 fatal 错误
错误信息里带 Unable to create '.git/index.lock': File exists，说明上一次 Git 操作（比如 commit 被 Ctrl+C 中断、IDE 插件卡住、容器内权限异常）没清理锁文件。
- 手动删：Windows 下用
del .git\index.lock，macOS/Linux 下用rm -f .git/index.lock - 别在多个终端/IDE 同时操作同一仓库 ——
index.lock是进程级互斥锁，不是线程级 - 在 Docker 容器中遇到此错，大概率是 UID/GID 不匹配导致无法写入，需用
--user $(id -u):$(id -g)启动容器 - CI 流水线中建议统一用
git -c core.precomposeUnicode=false checkout -B branchname FETCH_HEAD，绕过本地分支引用依赖
IDEA / VSCode 切换后编译/索引异常
分支切换成功，但 IDEA 里类找不到、Maven 报红、跳转到旧定义 —— 这不是 Git 的问题，是 IDE 缓存没跟上文件系统变化。
- 不要只点 “Reload project”，要触发完整索引重建：
File → Invalidate Caches and Restart → Invalidate and Restart - VSCode 中关闭所有窗口，删掉
.vscode目录和.git/index（谨慎），再重新打开 - 如果项目含 submodule，切换分支后务必运行
git submodule update --init --recursive，否则子模块仍停在旧 commit - Gradle/Maven 的
build目录建议设为excluded，避免被 IDE 当作源码索引
真正容易被忽略的是：Git 本身从不“记住”你上次在哪分支、哪些文件被 IDE 标记为“已更改”。所有状态都来自当前工作目录 + .git/index + .git/HEAD 的实时计算。任何外部工具（IDE、CI、容器）对这三个东西的读写延迟或权限干扰，都会表现为“切换失败”。所以查问题时，永远先看 git status 和 ls -la .git/，而不是直接重装插件或删整个 .idea。
