如何在Composer中配置SSH Key访问私有Git库
先说一个核心原则：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@地址，也不会自动回退到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"，或者已发布的标签版本，如"1.2.0"。
Git全局URL替换比硬写SSH更稳妥
直接在composer.json里写git@地址看似简单直接，但容易被IDE、CI工具或团队协作时的误操作所影响。利用Git自身的URL重写机制，往往更加健壮。
- 运行命令：
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，也不会自动信任未知的主机。
- 必须显式启动SSH agent并添加密钥：
eval "$(ssh-agent -s)"加上ssh-add <(echo "${{ secrets.SSH_KEY }}")（注意密钥内容不能包含\r\n这样的换行符）。 - 必须预先存储主机密钥：执行
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没有启动、主机密钥没有扫描、或者PHP进程读取了错误用户的~/.ssh目录。所以，最稳妥的做法是：先在目标环境中，让git clone命令能静默执行成功，然后再去调整composer.json的配置。
