composer如何通过SSH Key安装私有包_composer配置SSH权限详细教程【详解】

composer 通过 ssh Key 安装私有包的本质是确保 git 能用本地私钥拉取代码，关键在于 Git URL 必须为 SSH 格式（如 git@gitlab.example.com:group/repo.git）、SSH 密钥已正确生成并加载、ssh -T git@gitlab.example.com 能成功验证，而非修改 composer.json 或全局 Git 用户配置。

Composer 通过 SSH Key 安装私有包，本质是让 Git 能用你的私钥拉取代码，而不是让 Composer 本身“登录”。关键不在 composer.json 里写密码或 Token，而在本地 Git 的 SSH 配置是否生效、是否匹配仓库地址。

确认私有包 URL 是 SSH 格式

Composer 只会在 Git URL 是 SSH 形式时走 SSH 协议。https 地址（如 https://gitlab.example.com/group/repo.git）永远走 HTTPS 认证，哪怕你配了 SSH Key 也没用。

必须把 repositories 中的 URL 改成类似这样：

{     "type": "vcs",     "url": "git@gitlab.example.com:group/repo.git" }

常见错误：

• 混用协议：写成 ssh://git@gitlab.example.com/group/repo.git —— 多数 Git 服务（GitLab/github）不支持该格式，会连接失败
• 漏掉用户名 git@：只写 gitlab.example.com:group/repo.git，Git 无法识别为 SSH 地址
• 用了别名但没配置 ~/.ssh/config：比如写了 git@mygit，却没在 SSH 配置里定义 Host mygit

生成并加载正确的 SSH Key

Composer 不管理密钥，它调用 git clone，而 git 依赖系统 SSH Agent 或 ~/.ssh/config。所以重点是让 ssh -T git@gitlab.example.com 能通。

操作步骤：

• 用 ssh-keygen -t ed25519 -C "your_email@example.com" 生成新密钥（推荐 ed25519，比 rsa 更安全）
• 确保公钥已添加到 Git 托管平台（GitHub/GitLab/gitee）的 SSH Keys 设置页
• 运行 eval "$(ssh-agent -s)" 启动 agent（linux/macOS），再用 ssh-add ~/.ssh/id_ed25519 加载私钥
• windows 用户若用 Git bash，需确认 OpenSSH Authentication Agent 服务已启动，并执行 ssh-add

验证命令：ssh -T git@gitlab.example.com。成功返回类似 Welcome to GitLab, @username! 才算真正就绪。

绕过 host key 检查（仅限内网/测试环境）

如果私有 Git 服务器用的是自签名域名或内网 IP（如 git.internal），首次连接常因未知 host key 失败，报错类似：

The authenticity of host 'git.internal (10.0.1.5)' can't be established.

这不是权限问题，而是 SSH 拒绝未验证的 host。临时解决（不推荐线上）：

# 在 ~/.ssh/config 中追加 Host git.internal     StrictHostKeyChecking no     UserKnownHostsFile /dev/null

更稳妥的做法是手动执行一次 ssh git@git.internal，接受 host key，它会自动存入 ~/.ssh/known_hosts。之后 Composer 就能静默通过。

避免全局 Git 用户邮箱污染提交记录

很多人为了“让 SSH 生效”在全局设了 git config --global user.email，结果所有本地 commit 都带上错误邮箱。其实完全没必要。

SSH 认证和 Git 提交身份是两回事：

• SSH 只认密钥和服务器端绑定的账号（即你添加公钥时用的 Git 平台账号）
• commit 作者信息由 git config user.name/user.email 控制，且应按项目设置（--local），而非 --global

如果你发现 composer install 卡住或报 Permission denied (publickey)，优先检查 ssh -T 是否通、URL 是否为 git@... 格式、私钥是否被 ssh-agent 正确加载——这些点比改 Composer 配置重要得多。