github-protocols 配置项决定 Composer 访问 GitHub 仓库时的协议优先级,支持 https、ssh 和 git(已弃用)。默认按顺序尝试,可手动设置以优化认证与网络兼容性。例如企业网络屏蔽 SSH 时应优先 https,CI/CD 环境则推荐 ssh 以避免凭证输入。配置影响 URL 映射:https 协议使用 https://github.com/user/repo.git,ssh 使用 git@github.com:user/repo.git。不当配置可能导致拉取失败或重复认证。合理设置可提升依赖安装效率与稳定性,尤其在复杂网络或多团队协作场景中。

Composer 的 github-protocols 配置项决定了它在与 GitHub 仓库交互时使用哪种协议来克隆或下载项目。这个设置主要影响依赖包从 GitHub 获取的方式,特别是在处理私有仓库或网络受限环境时尤为关键。
github-protocols 是什么?
该配置项指定 Composer 在访问 GitHub 项目时优先使用的传输协议。支持的协议包括:https、ssh 和 git(已基本弃用)。默认情况下,Composer 会尝试按顺序使用这些协议,但你可以通过配置改变其行为。
如何影响与 GitHub 的交互?
不同的协议选择会影响身份验证方式、网络穿透能力和安全性:
- https:最常用,适合大多数情况。需要 token 或用户名密码进行私有仓库认证。易于在防火墙后工作。
- ssh:更安全,使用 SSH 密钥认证。适合自动化部署和私有环境。要求提前配置好 SSH 密钥并添加到 GitHub 账户。
- git:匿名只读协议,不推荐使用,且 GitHub 已逐步限制此协议的访问。
如果你设置了 "github-protocols": ["ssh", "https"],Composer 会优先尝试通过 SSH 克隆仓库。若 SSH 不可用(如未配置密钥),则回退到 HTTPS。
实际应用场景
某些企业网络可能屏蔽 SSH 端口(22),此时即使你配置了 SSH 密钥也无法连接。这时应改为优先使用 HTTPS:
{
"config": {
"github-protocols": ["https"]
}
}
相反,在 CI/CD 环境中,通常配置了 SSH agent,使用 SSH 更方便且无需频繁输入凭证:
{
"config": {
"github-protocols": ["ssh"]
}
注意事项
Composer 会在内部将 GitHub 的仓库 URL 自动映射为对应协议的地址。例如:
- HTTPS 模式下:
github.com/user/repo→https://github.com/user/repo.git - SSH 模式下:
github.com/user/repo→git@github.com:user/repo.git
如果协议顺序不当或缺少必要认证信息,可能导致拉取失败、卡顿或要求重复输入凭据。
基本上就这些。合理设置 github-protocols 可显著提升依赖安装效率和稳定性,尤其在混合网络环境或多团队协作项目中。










