私有 Git 仓库拉取失败因 Composer 不自动读取系统凭据，须在 composer.json 的 config → http-basic 中按域名配置 PAT，或用 composer config -g 全局设置；repositories 中的 credentials 无效，且需注意重定向导致认证头丢失。
私有 Git 仓库拉取失败：401 Unauthorized 或 fatal: could not read Username
Composer 访问私有 Git 仓库（如 GitHub/GitLab 私有项目）时，直接报 401 Unauthorized 或卡在 fatal: could not read Username，说明它根本没拿到凭据。Composer 不会自动读取系统 git 凭据管理器（比如 git config --global credential.helper 的配置），也不走 SSH agent（除非你显式用 ssh:// 协议）。必须在 composer.json 或全局配置里明确定义 HTTP Basic Auth。
在 composer.json 的 repositories 中写 credentials 不起作用
很多人误以为在 repositories 数组里加 "username" 和 "password" 字段就能生效——这是错的。repositories 只描述源地址和类型，不承载认证信息。真正起作用的是 http-basic 配置块，它按域名匹配，与 repositories 是解耦的。
正确做法是：在 composer.json 顶层加 config → http-basic，键为仓库域名（不含协议和路径），值为账号密码对象：
{
"config": {
"http-basic": {
"gitlab.example.com": {
"username": "your-token-or-username",
"password": "your-personal-access-token"
}
}
},
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/group/project.git"
}
]
}
-
gitlab.example.com必须和url中的 host 完全一致（不带端口、不带www、不带路径） - 密码字段推荐填 Personal Access Token（PAT），不是登录密码；GitHub 已禁用密码认证，GitLab 也建议用 token
- 如果用的是自建 GitLab 且启用了双因素，只能用 PAT，不能用用户名+密码组合
全局配置 vs 项目配置：token 泄露风险怎么控？
把 token 写进 composer.json 是危险的——它会被提交到代码库。更安全的做法是用 Composer 全局凭据配置，只存在本地：composer config -g http-basic.gitlab.example.com username token。这条命令会在 ~/.composer/auth.json 里写入加密后的凭据（实际是明文存储，但文件权限默认为 600）。
注意几个关键点：
- 执行命令时，
username和token是两个独立参数，不要加引号包裹整个"username token" - 如果域名含端口（如
gitlab.example.com:8443），必须把端口一起写进 key，http-basic.gitlab.example.com:8443 - CI 环境中，建议用环境变量注入：
COMPOSER_AUTH='{"http-basic":{"gitlab.example.com":{"username":"$GIT_USER","password":"$GIT_TOKEN"}}}' composer install
HTTPS 重定向导致认证头丢失：GitLab/Bitbucket 常见陷阱
某些私有 Git 服务（尤其是旧版 GitLab 或自建 Bitbucket Server）会把 https://git.example.com/repo.git 重定向到另一个 URL（比如加了 /scm/ 路径）。Composer 默认不转发 Authorization 头到重定向后的地址，结果就是「凭据已配，但还是 401」。
解决方法只有两个：
- 改用
ssh://协议（前提是服务支持且你已配好 SSH key），绕过 HTTP 认证链 - 在
composer.json的repositories中，把url直接写成重定向后的最终地址（用curl -I https://...确认 Location 头），让 Composer 不触发跳转
这个坑没有报错提示，只会静默失败或卡住，排查时得抓包看 HTTP 流程。
HTTP Basic Auth 这块最麻烦的不是配置语法，而是凭据生命周期管理、重定向兼容性、以及不同 Git 托管平台对 token 类型的隐式要求——比如 GitHub 要 repo scope，GitLab 要 read_repository，少一个权限就拉不动子模块。
