“git@github.com: Permission denied (publickey)”根本原因是SSH agent未启动或密钥未加载，且Git未正确调用agent；需执行eval $(ssh-agent)启动agent、ssh-add加载私钥，并全局配置git config --global core.sshCommand "ssh -o ForwardAgent=yes"确保透传。
“git@github.com: Permission denied (publickey)” 不是密码错，是 SSH agent 没传过去，或 Git 没用上它。
ssh-add -l 为空？说明 agent 根本没启动或密钥没加载
在执行 composer install 的机器上（尤其是 CI/CD 服务器、Docker 容器、跳板机），直接运行：
-
ssh-add -l—— 如果输出为空，或报Could not open a connection to your authentication agent，说明当前 shell 没继承到 agent - 临时修复：运行
eval $(ssh-agent)启动 agent，再ssh-add ~/.ssh/id_rsa（或对应私钥路径） - 但注意：这只是当前 shell 有效；若你是通过
ssh user@host连上去的，必须确保连接时加了-o ForwardAgent=yes，否则子进程（如 Git）根本看不到你的密钥 - 别依赖
~/.ssh/config里的ForwardAgent yes—— 检查 Host 别名是否真匹配目标主机名（比如你连的是gitlab.example.com，但 config 里只写了Host gitlab，那就不生效）
git config --global core.sshCommand 是关键补丁
即使 SSH 连接启用了 forwarding，Git 在非交互式环境（CI、Docker、cron）中仍可能绕过 agent。强制它走标准 OpenSSH 并透传 agent：
- 运行
git config --global core.sshCommand "ssh -o ForwardAgent=yes" - 这个配置比改
~/.ssh/config更可靠，因为它作用于所有 Git 的 SSH 调用，不依赖连接上下文 - 验证是否生效：
git ls-remote git@github.com:your-org/private-repo.git，能返回 refs 表示通了 - 绝对不要写成
core.sshCommand="ssh -i /path/to/key"—— 这会硬编码私钥，绕过 agent，失去多密钥管理和安全性
auth.json 或 github-oauth 配置对 SSH 场景完全无效
Composer 自身不处理 SSH 认证，它只是调用系统 git 命令。所以以下操作全是徒劳：
- 在
auth.json里配http-basic或github-oauth—— 对git@协议的仓库不起作用 - 在
composer.json的repositories中写"url": "ssh://git@..."或幻想 Composer 能接管认证 —— 不行 - 把私钥文件 chmod 600 都没用，关键是 agent 是否可达、Git 是否被正确配置去用它
- 如果
ssh -T git@github.com都失败，问题不在 Composer，先解决基础 SSH 连通性
CI/CD 环境下最容易漏掉的三件事
在 GitHub Actions、GitLab CI、Jenkins 等环境中，SSH agent forwarding 很容易断链：
- GitHub Actions 默认禁用 agent forwarding；必须用
ssh-agentaction 显式注入，并配合add-ssh-key步骤 - GitLab CI 中，
before_script里的eval $(ssh-agent)只对当前 step 生效；后续 job 需要重新加载，或改用SSH_AUTH_SOCK环境变量传递 - Docker 容器内默认无 ssh-agent；除非你用
--mount=type=ssh挂载，否则ssh-add -l必然为空 - 所有场景下，
git config --global core.sshCommand这一步不能省，它是最后的兜底保障
真正卡住人的地方，往往不是密钥本身，而是 agent 的生命周期管理与 Git 的调用链路是否完整透传——每层都得确认，少一环就 Permission denied (publickey)。
