根本原因是系统级 Git 客户端无权限访问私有仓库，Composer 仅解析配置并调用 git clone；HTTPS 报 401 因 token 错误，SSH 报 Permission denied 因密钥未正确加载或配置。
composer拉取私有 Git 仓库时提示 401 Unauthorized 或 Permission denied (publickey)
根本原因不是 Composer 本身的问题，而是它背后调用的 git clone 命令没权限访问你的私有仓库。Composer 只负责读 composer.json 里的 repositories 配置，真正干活的是系统级的 Git 客户端。
常见错误现象：
- 执行
composer install卡在Cloning into 'xxx'...，然后报fatal: Could not read from remote repository. - 用 HTTPS 地址时提示
401（账号密码或 token 不对） - 用 SSH 地址时提示
Permission denied (publickey)（本地没配好密钥或 agent 没加载）
实操建议：
- 优先用 SSH 方式（更安全、免输 token），确认
git@github.com:xxx/yyy.git这类地址能在终端直接git clone成功 - 检查
ssh -T git@github.com（或对应 Git 平台域名）是否返回欢迎信息；如果失败，说明密钥没加进ssh-agent或没配对 - 确保
~/.ssh/config里为该 Git 域名设置了正确的IdentityFile和User git - HTTPS 方式需用 Personal Access Token 替代密码（GitHub 已禁用账户密码），token 要带
repo权限，并写在 URL 里：https://<code>your_token@github.com/xxx/yyy.git
在 composer.json 中正确声明私有仓库
不填对 type 和 url，Composer 根本不会走 Git 流程，可能静默 fallback 到 Packagist，或者报 Could not find package xxx。
使用场景：你维护一个内部组件库，想让多个项目通过 Composer 复用它。
实操建议：
-
type必须是vcs（不是package或path），否则 Composer 不会尝试克隆 -
url必须是完整可访问的 Git 地址，且协议要和你的认证方式一致（SSH 用git@，HTTPS 用https://） - 不要在
repositories里写错顺序——私有源应放在packagist.org之前，否则可能被跳过 - 示例片段：
{
"repositories": [
{
"type": "vcs",
"url": "git@gitlab.example.com:mygroup/my-package.git"
}
],
"require": {
"mygroup/my-package": "dev-main"
}
}
composer config 设置全局 Git 鉴权方式失效？
composer config -g github-oauth.github.com <code>your_token 这类命令只对 GitHub 官方 API 有效（比如下载 zip 包、查 tag），对私有 Git 仓库的 git clone 没影响——它压根不经过 Composer 的 OAuth 配置。
性能 / 兼容性影响：
- 滥用
github-oauth配置私有 GitLab 或自建 Gitea，会导致 Composer 在元数据请求阶段就失败，但错误提示很模糊（比如Could not fetch） - GitLab 私有实例要用
gitlab-token配置，且仅限于通过 GitLab API 获取包信息，不替代 SSH/HTTPS 认证 - 真正起作用的还是系统 Git 自身的凭据管理（
git credential、~/.netrc、SSH agent）
CI 环境下拉取私有仓库总失败
本地能跑通，CI（如 GitHub Actions、GitLab CI）却卡住，大概率是环境隔离导致密钥或凭据没注入。
容易踩的坑：
- CI 默认不启用 SSH agent 转发，
ssh-add加载的密钥在子 shell 里不可见 - 用 HTTPS + token 时，把 token 写死在
composer.json或脚本里，属于严重安全风险 - 某些 CI 镜像自带旧版 Git，不支持
git credential helper store，导致凭据缓存失败
实操建议：
- GitHub Actions 推荐用
webfactory/ssh-agentAction 注入密钥，而不是手动echo ${{ secrets.SSH_KEY }} | ssh-add - - GitLab CI 可用
SSH_KNOWN_HOSTS和SSH_PRIVATE_KEY变量配合before_script初始化 SSH - 避免在任何配置文件中硬编码 token；HTTPS 场景下，用
git config --global url."https://${{ secrets.GIT_TOKEN }}@gitlab.example.com".insteadOf "https://gitlab.example.com"
最常被忽略的一点：私有仓库的 composer.json 里必须有合法的 name 字段（格式为 vendor/name），且和 require 中写的完全一致——大小写、分隔符、连字符都不能错，否则 Composer 找不到包，也不会报 Git 错误，而是静默失败。
