如何在Composer中配置SSH Key访问私有Git库

如何在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的配置。