根本原因是Composer调用git clone时SSH密钥未正确加载或配置，需确保git clone git@host:path.git能免密成功；验证ssh -T git@host返回Hi username!，检查ssh-add -l、~/.ssh/config主机名匹配、私钥权限600、composer.json中vcs类型与SSH URL一致。
根本原因不是 Composer 本身要密码，而是它调用的 git clone 命令在走 SSH 协议时没拿到可用密钥——要么没加载，要么路径错，要么权限不对，要么 ~/.ssh/config 没配对主机名。
确认 git clone git@host:path.git 是否真能免密
这是唯一可信的验证动作。Composer 不会报“密钥没加”，只会在后台卡住或报 Permission denied (publickey)。
- 运行
ssh -T git@github.com（把域名换成你的 Git 平台，如git@gitlab.example.com），必须看到类似Hi username! You've successfully authenticated才算通 - 如果提示输密码或 Permission denied，说明
ssh-agent没加载密钥：执行ssh-add -l查看是否列出；没列就运行ssh-add ~/.ssh/id_ed25519（路径按你实际密钥位置改） - 手动试克隆：
git clone git@github.com:org/private-repo.git，必须全程无交互、无密码提示、能拉下代码 - Windows 用户注意：Git Bash 和 PowerShell 的
ssh-agent不互通，建议统一在 Git Bash 里执行所有操作
~/.ssh/config 必须严格匹配 URL 中的主机名
Composer 不读 Host 别名（比如 Host gh），只认完整域名。写错一个字符，SSH 就找不到密钥。
Github Xiaoshu
下载
使用 `gh` CLI 与 GitHub 交互。通过`gh issue`、`gh pr`、`gh run` 和 `gh api` 管理 issue、PR、CI 运行以及高级查询。
- 假设仓库 URL 是
git@gitlab.example.com:group/pkg.git，那~/.ssh/config里必须有段以Host gitlab.example.com开头的配置 -
IdentityFile必须是绝对路径，例如~/.ssh/id_rsa_gitlab；相对路径（如./id_rsa）会被从当前工作目录解析，而 Composer 启动时工作目录不固定 - 每段至少含三行：
Host（完全匹配）、User git（所有 Git 平台 SSH 入口用户都是git）、IdentityFile（指向私钥） - 如果用了非标准端口或跳板机，必须显式加
Port 2222或ProxyJump jump-host，否则子进程看不到这些设置
composer.json 里必须用 vcs 类型 + git@ 格式 URL
写成 HTTPS 地址、ssh://、网页链接，或者漏掉 "type": "vcs"，Composer 都不会走 SSH，甚至可能静默 fallback 到 Packagist。
- repositories 数组里必须这样写：
{ "type": "vcs", "url": "git@gitlab.example.com:group/private-pkg.git" } - URL 不能带
https://、不能是ssh://、不能缺.git后缀、不能写成git@gitlab.example.com/group/private-pkg（少斜杠） - require 中的包名（如
"group/private-pkg"）必须和私有库根目录下composer.json里的"name"字段**完全一致**（包括大小写、连字符） - 删掉
vendor/和composer.lock再重装，避免缓存旧的 HTTPS 元数据导致降级失败
CI 环境下容易忽略的用户与权限问题
本地能跑不代表 CI 能跑。CI 默认用 root 或 www-data 运行，但密钥往往只放在普通用户家目录下。
- 先查 CI 中谁在执行：
whoami，再确认密钥是否放在该用户的~/.ssh/下（不是/home/user/.ssh/，而是/root/.ssh/或/var/www/.ssh/） - 私钥文件权限必须是
600：chmod 600 ~/.ssh/id_rsa，否则 SSH 直接拒绝读取 - CI 中别依赖全局
git config --global url."git@...".insteadOf，容易和其他项目冲突；优先用项目级repositories显式声明 - GitHub Actions 或 GitLab CI 中，记得用
ssh-agentaction 加载密钥，并确保~/.ssh/config已正确注入
最常被跳过的其实是第一件事：没验证 git clone 是否真能免密。只要这一步不通，后面所有 Composer 配置都白搭。密钥、config、URL、type 四者必须全部对齐，缺一不可。
