Composer 依赖 Git 的 SSH 配置，需确保 git clone git@github.com:org/repo.git 静默成功：先用 ssh -T git@github.com 验证认证，再检查 ssh-add -l 是否加载密钥、~/.ssh/config 是否正确配置，composer.json 中 repositories 必须为 vcs 类型且 url 为 SSH 格式，包名与私有库 composer.json 中 name 严格一致，版本须用 dev-main 等显式标识。
Composer 本身不处理 SSH 密钥，它完全依赖 Git 的 SSH 配置。只要 git clone git@github.com:org/repo.git 能静默成功，Composer 就能拉下私有库；否则所有配置都是白搭。
确认 SSH 密钥已加载且 git clone 可行
这是最常跳过的验证环节，也是 90% 失败的根源。Composer 不会报“密钥没加”，只会卡在 Cloning into '/tmp/xxx' 或直接退出。
- 运行
ssh -T git@github.com（或你的 Git 域名），必须看到Hi username! You've successfully authenticated - 若提示
Permission denied (publickey)，检查是否加载了密钥：ssh-add -l；没列出就执行ssh-add ~/.ssh/id_ed25519（路径按实际调整） - 手动测试克隆：
git clone git@github.com:org/private-repo.git，必须能完整拉下代码，中途不能输密码、不能停住 - 如果用自定义域名（如
git.internal），确保~/.ssh/config中Host名与 URL 完全一致，且含IdentityFile和User git
composer.json 中必须用 vcs 类型 + SSH URL
写错类型或协议，Composer 就当仓库不存在。它不会自动识别 git@ 地址，也不会 fallback 到 HTTPS。
-
repositories数组里必须设"type": "vcs"，不是"git"、"package"或留空 -
url字段必须是完整 SSH 格式："git@github.com:org/private-repo.git"，不能是https://、ssh://或网页地址 -
require中的包名（如"org/private-repo"）必须和私有库根目录下composer.json里的"name"字段**逐字符一致**（大小写敏感） - 版本不能写
"*"或"^1.0"；得用"dev-main"、"dev-develop"或已打 tag 的"1.2.0"
Git 全局 URL 替换比硬写 SSH 更稳妥
直接在 composer.json 里写 git@ 地址看似简单，但容易被 IDE、CI 工具或团队协作误改。用 Git 自身的重写机制更健壮。
- 运行
git config --global url."git@github.com:".insteadOf "https://github.com/"，之后所有https://github.com/org/repo都会自动转成 SSH - 这样你就能在
composer.json里放心写 HTTPS 地址："url": "https://github.com/org/private-repo.git"，既语义清晰又兼容 CI 工具解析 - 注意：斜杠位置不能错——
insteadOf后必须是"https://github.com/"（末尾带/），否则不生效 - 该配置影响所有 Git 操作，如需局部控制，改用
--local替代--global
CI 环境最容易漏掉的三件事
本地能跑 ≠ CI 能跑。GitHub Actions、GitLab CI 这类环境默认不加载 SSH agent，也不信任未知 host。
- 必须显式启动 agent 并添加密钥：
eval "$(ssh-agent -s)"+ssh-add <(echo "${{ secrets.SSH_KEY }}")（注意密钥内容不能含\r\n） - 必须预存 host key：
ssh-keyscan github.com >> ~/.ssh/known_hosts，否则报Host key verification failed - PHP 进程用户 ≠ 当前 shell 用户（比如
www-data或runner）。SSH 密钥、auth.json、~/.ssh/config都得放在该用户的家目录下，且权限为600
真正卡住的地方往往不是 Composer 配置，而是 SSH agent 没启、host key 没扫、或者 PHP 进程读错了用户的 ~/.ssh 目录。先让 git clone 在目标环境静默跑通，再动 composer.json。
