Composer报git错误非自身故障，而是因dev分支、vcs仓库或--prefer-source等场景必须调用系统git命令，若git缺失、PATH未配置、版本低于2.19.2、SSH/HTTPS协议异常、user.name/email未设置或vendor残留损坏.git目录，均会导致失败；验证需新开终端执行git --version和composer diagnose，修复须按环境安装完整git并正确配置PATH，或临时用--prefer-dist绕过。
Composer 报 git 相关错误，不是 Composer 本身坏了，而是它在特定条件下必须调用系统 git 命令，而这个命令不可用、版本太低、配置不全，或目标仓库状态异常。
git --version 都失败，说明系统级 Git 缺失或 PATH 没生效
Composer 不会自己带 git，它只负责调用 git 命令。如果连 git --version 都报 command not found 或 git is not recognized，问题就出在环境上：
- Windows：Git for Windows 安装时没勾选 “Git from the command line and also from 3rd-party software” —— 这个选项才把
git.exe加进系统 PATH；装完必须新开终端，旧窗口不会自动加载新 PATH - macOS：别依赖 Xcode 自带的阉割版
git（它缺git config等子命令），用brew install git装完整版，并确认/opt/homebrew/bin（Apple Silicon）或/usr/local/bin（Intel）在$PATH前置位置 - Linux（如 Ubuntu）：只装
git-core不够，得运行sudo apt install git（这是元包，含全部依赖） - Docker / CI 环境：基础镜像里默认没 git，Debian/Ubuntu 镜像加
RUN apt-get update && apt-get install -y git，Alpine 加RUN apk add --no-cache git
验证是否真生效：别只信 IDE 或 shell 配置文件，新开一个终端，跑 git --version 和 composer diagnose，看后者输出里有没有 Git binary found at。
git --version 成功但 clone 失败，重点查协议、用户配置和仓库状态
能执行 git --version，不代表 git clone 就一定能通。常见卡点是协议不匹配或本地 Git 配置缺失：
- 私有仓库用 SSH（
git@github.com:user/repo.git）但没配密钥？先手动试ssh -T git@github.com；失败就补密钥或换 HTTPS - 公司网络屏蔽 SSH 端口（22）？强制 Composer 走 HTTPS：
composer config -g github-protocols https，或设环境变量COMPOSER_GITHUB_PROTOCOL=https - Git 全局没设
user.name和user.email？某些容器或精简环境会因此拒绝克隆，哪怕只是读操作：git config --global user.name "a"和git config --global user.email "a@a"就行 - vendor 下某个包目录里残留了损坏的
.git文件夹？Composer 会误判为已检出仓库，然后执行git rev-parse报fatal: not a git repository；用find vendor -name ".git" -type d找出来删掉
--prefer-dist 能绕过 git，但不是所有场景都适用
加 --prefer-dist 是最轻量的临时解法，它让 Composer 强制走 ZIP/TAR 归档下载，跳过所有 git clone：
- 适合生产部署、CI 构建、Docker 镜像制作等不需要改依赖源码的场景
- 但对私有仓库、未配置
"archive"的 GitHub repo、或composer.json里写了"type": "vcs"的自定义源，可能 fallback 回 git ——--prefer-dist不是银弹 - 若你用了
"preferred-install": "source"或COMPOSER_PREFER_SOURCE=1，这个参数会被覆盖，得先关掉它们
命令示例：composer install --prefer-dist --no-interaction --optimize-autoloader。
Git 版本低于 2.19.2 会硬性拒绝，升级是唯一解
Composer 内部做了版本校验，git --version 输出低于 2.19.2 时，会直接报 The git executable is too old，且 --ignore-platform-reqs 无效：
- Windows：用
winget install --id Git.Git -e或重装官网最新安装包（2026 年 4 月已是 2.45.0），安装时仍要选对 PATH 选项 - macOS：Homebrew 装完后检查
which git是否指向/opt/homebrew/bin/git（Apple Silicon）或/usr/local/bin/git（Intel），避免 PATH 里有旧版路径排在前面 - Linux（如 CentOS）：系统仓库的 git 版本普遍太老，必须源码编译安装，并把新
git路径（如/usr/local/bin）加到 PATH 开头
最容易被忽略的是：IDE（如 PHPStorm）或 Web 服务器（如 www-data 用户）可能缓存了旧 git 路径，即使你本地升级了，它们仍调用老版本 —— 得单独检查这些上下文里的 PATH 和 which git。
