Git二进制缺失或PATH未生效导致VCS解析失败，根本原因是Composer在拉取dev分支、启用--prefer-source或解析私有VCS仓库时必须调用系统git命令；若git--version报错，则需按系统分别修复：Windows须勾选Git安装时的“添加到PATH”选项并新开终端，macOS须用brew安装完整版git并确保其路径在$PATH前置，Linux需安装完整git元包，Docker/CI镜像中须显式安装git，最后通过git--version和composerdiagnose验证是否显示“Gitbinaryfoundat”。
Git 二进制缺失或 PATH 未生效导致 VCS 解析失败
Composer 在需要拉取 dev 分支、启用 --prefer-source 或解析私有 VCS 仓库时，必须调用系统 git 命令。如果连 git --version 都报错，就不是 Composer 的问题，而是环境没配好。
- 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
验证方式：新开终端，执行 git --version 和 composer diagnose，后者输出中必须出现 Git binary found at 才算真正生效。
Git 用户信息未配置引发 clone 中断
某些 Git 服务（尤其企业自建 GitLab 或旧版 GitHub）在克隆时会检查本地 user.name 和 user.email。缺配置会导致 git clone 卡住或静默失败，进而让 Composer 报 “Could not read from remote repository”。
- 运行
git config --global user.name "Your Name" - 运行
git config --global user.email "your-email@example.com" - 不需要和 GitHub 账号邮箱一致，只要非空即可
- CI 环境也需在构建脚本开头显式设置，不能依赖用户 home 目录下的配置
注意：这个配置不是为了提交代码，而是绕过 Git 内部的初始化校验逻辑——不设它，clone 就可能被阻断。
SSH 密钥未加载或权限失效导致私有仓库拒绝访问
当 composer.json 里 repositories 指向 SSH 地址（如 git@github.com:org/repo.git），而 ssh -T git@github.com 失败时，Composer 必然卡在 VCS 解析阶段。
辅助阅读和快速理解 GitHub/Git 项目结构与核心价值的结构化方法论。 当用户请求"分析这个 GitHub 项目"、"帮我读一下这个 repo"、"了解这个项目是做什么的"、 "怎么用这个项目"、"怎么跑这个项目"、"这个项目用了哪些技术"，或任何涉及 GitHub/Git 仓库阅读、理解、技术评估、快速上...
- 先手动运行
ssh -T git@github.com（或对应托管平台域名），看是否返回欢迎信息 - 若提示
Permission denied (publickey)，检查~/.ssh/id_rsa.pub是否已添加到平台 SSH Keys 设置中 - 若用的是非默认密钥名（如
id_ed25519），需在~/.ssh/config中显式指定：Host github.com IdentityFile ~/.ssh/id_ed25519
- 避免混用 SSH 和 HTTPS：同一项目中不要一部分包走 SSH、另一部分走 HTTPS，否则容易因凭据管理混乱导致间歇性失败
临时验证是否是 SSH 问题？把 repositories.url 改成 HTTPS 格式（如 https://github.com/org/repo.git），并确保已配置 GitHub OAuth Token（composer config --global github-oauth.github.com TOKEN）。
Git 缓存残留导致地址解析僵化
Git 权限变更（如组织迁移、SSH 改 HTTPS）、仓库私有/公开状态切换后，Composer 仍固执地尝试用缓存里的旧 URL 克隆，是因为它把旧地址“记死”在三处：
-
vendor/vendor-name/package-name/下残留的损坏 Git 工作目录 -
~/.composer/cache/vcs/中的缓存目录（如https---github.com-vendor-package.git/） -
vendor/composer/installed.json中硬编码的source.url和commit
只跑 composer clear-cache 不够——它清不掉前两项。正确做法是：rm -rf vendor/vendor-name/package-name ~/.composer/cache/vcs/https---github.com-vendor-package.git vendor/composer/installed.json，再执行 composer update vendor/package-name --no-cache -vvv，观察日志里 Cloning into 行是否已换成新地址。若仍不对，检查 composer.json 的 repositories 是否还写着旧 URL。
最常被忽略的一点：VCS 解析失败往往不是单点问题，而是 Git 二进制、用户配置、密钥、缓存四者中至少两个同时出状况。别只 fix 一个就以为好了，建议按顺序逐项验证。
