当 Claude Code 找不到 Git（但终端里 Git 一切正常）

前几天我遇到了一个令人沮丧的边界情况：Claude 桌面应用里的 Claude Code 面板反复弹出模态框，要求我安装 Git。

运行本地会话需要 Git。 在终端中运行 xcode-select --install 以安装 Command Line Tools，或直接下载 Git——也可以切换到远程环境。

问题在于：Git 明明已经装好了。

在终端里运行 git --version 立刻返回了有效的版本号。Claude Code 在命令行下运行得毫无问题。唯独桌面 GUI 应用拒绝承认 Git 的存在。

由于我运行的是 macOS 27 测试版，我的第一反应就是“测试版 bug”。这个想当然让我白白浪费了一个小时钻牛角尖。以下是完整的复盘，包括那些错误的判断。

第一个猜测：Command Line Tools 损坏

在 macOS 上，/usr/bin/git 实际上并不是 Git 二进制文件本身——它是一个垫片启动器，会把命令转发到 xcode-select 当前指向的开发者目录。macOS 大版本升级经常破坏或重置这个指针，因此每当系统更新后 Git 突然“消失”，过期的 Command Line Tools 安装就成了教科书式的罪魁祸首。

由于测试版系统的直接软件包更新不一定能立即通过软件更新推送，我直接从 Apple Developer Downloads 页面下载了 .dmg，安装后手动重置了开发者目录：

zsh

sudo xcode-select -s /Library/Developer/CommandLineTools
git --version   # git version 2.54.0 (Apple Git-157)
clang --version # Apple clang version 21.0.0

命令行里一切正常：git 可用，clang 也可用。

然而，重新打开桌面应用后，那个对话框依然顽固地存在。

如果 Git 在 shell 中正常工作，却在 GUI 中不可见，那问题就不在 Git 本身——而在于应用解析环境二进制文件的方式。

第二个猜测：GUI 的 PATH 环境变量

这是 macOS 上一个经典的绊线问题。从 Finder、Dock 或 Spotlight 启动的应用不会继承你在 shell 启动脚本（.zshrc 或 .bash_profile）中设置的环境变量或自定义 PATH 定义。GUI 应用是在一个极简的 launchd 上下文中启动的。你的 shell 能轻松解析的二进制文件，对 GUI 应用来说可能完全不可见。

此外，Claude 桌面应用会在启动时缓存其环境。如果应用运行期间你修复了路径问题，应用对系统的认知会一直停留在旧状态，直到彻底重启（右键点击 Dock 图标 → 退出，而不仅仅是关闭窗口）。

我检查了系统默认的 launchd 配置：

zsh

launchctl getenv PATH
# (empty)

返回为空。于是我显式地为 launchd 设置了一个基线 PATH：

zsh

sudo launchctl config user path "/Library/Developer/CommandLineTools/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin"

在完全重启系统后，launchctl getenv PATH 确认了更新后的环境。我重新启动了 Claude Desktop，满心期待能解决问题。

结果弹出了完全相同的对话框。

到这一步，我已经诊断并修复了两个真实的系统问题——一个损坏的 CLI 工具指针和一个过于精简的 GUI 环境。这两个问题都值得修复，但都不是根本原因。

根本原因：一个来自 2022 年的失效符号链接

我不再猜测，直接翻查实际进程日志。在 GitHub issue（#54754）中看到了这个确切行为的描述，揭示了底层的失败模式：

text

Failed to spawn /Users/xxx/bin/git: spawn /Users/xxx/bin/git EACCES

应用并不是找不到 Git——它是在系统执行顺序中先找到了一个损坏的 Git 条目，并在尝试执行时因 EACCES（权限被拒绝）错误而失败。

当桌面应用启动子进程时，它会尝试执行在解析路径中找到的第一个匹配项。如果该候选失败或缺少执行权限，进程会立即中止，而不是像交互式 shell 那样继续尝试后续匹配。

我运行了一次解析检查，查看所有已注册的 git 二进制路径：

zsh

which -a git
# /usr/local/bin/git
# /usr/bin/git

找到了：/usr/local/bin/git 排在标准系统路径 /usr/bin/git 之前。

检查该文件后发现其来源：

zsh

ls -la /usr/local/bin/git
# lrwxr-xr-x  1 epona  admin  28 Feb  8  2022 /usr/local/bin/git -> ../Cellar/git/2.35.1/bin/git

这是一个 2022 年 2 月遗留的符号链接。它指向 ../Cellar/git/2.35.1/，这是多年前已被清除的旧版 Intel 版 Homebrew 安装的残留物。（/usr/local 是旧版 x86 Homebrew 路径；Apple Silicon 版 Homebrew 运行在 /opt/homebrew 下）。

由于目标路径已不存在，直接运行这个失效引用会抛出错误。

解决方案只需一条清理命令：

zsh

sudo rm /usr/local/bin/git

再次验证活动路径：

zsh

which -a git
# /usr/bin/git

git --version
# git version 2.54.0 (Apple Git-157)

我强制退出桌面应用并重新启动。提示完全消失了。

关键要点

Shell 会掩盖损坏的路径；GUI 应用不会。 交互式 shell 可能因别名配置和环境处理方式而隐藏孤立二进制文件，但基于 spawn 的应用调用会在遇到第一个无效条目时直接失败。
使用 `which -a`，而不仅仅是 `which`。 运行基本的 which git 只显示当前生效的路径，而 which -a 会按优先级顺序列出环境中所有实例——让被遮蔽或失效的二进制文件一目了然。
尽早查看应用错误日志。 修复中间环境问题（如 Command Line Tools 或 launchctl 变量）看似有成效，但直接阅读实际的子进程 spawn 日志，几秒钟内就精准定位了路径失败的具体位置。

如果 GUI 开发工具报告某个 CLI 二进制文件缺失，而它在终端中却运行正常，请运行 which -a <tool>——很可能有一个旧的符号链接排在第一位。

第一个猜测：Command Line Tools 损坏

第二个猜测：GUI 的 PATH 环境变量

根本原因：一个来自 2022 年的失效符号链接

关键要点

相关文章