composer config --auth 写入 GitLab 凭据失败的主因是域名未完全匹配：http-basic.gitlab.example.com 中的域名必须与 repositories.url 的 host 部分（不含协议、端口、路径）严格一致，且须用 http-basic 字段、username 填 git、password 填含 read_api 和 read_repository 权限的 PAT；gitlab-token 字段无效，SSH 方式不适用该命令。
composer config --auth 写入 GitLab 域名凭据失败？检查域名是否完全匹配
直接运行 composer config --auth http-basic.gitlab.example.com username password 是最简方式，但 90% 的失败源于域名不一致：auth.json 中的 key 必须和 composer.json 里 repositories.url 的 host 部分完全相同（不含协议、端口、路径）。比如 URL 是 https://gitlab.example.com:8443/group/pkg.git，那配置命令里的域名就得是 gitlab.example.com:8443，漏掉端口或写成 https://gitlab.example.com 都会静默失效。
常见错误现象：composer install 仍提示 Could not fetch https://gitlab.example.com/... 或反复要求输入凭据 —— 这说明 Composer 根本没读到 auth.json 里的凭据。
- 运行
composer config --list --global查看是否已写入对应域名条目 - 确认
COMPOSER_HOME路径（通常是~/.composer），检查auth.json文件权限是否为600（Linux/macOS） - 别把 token 当作 password 直接塞进 URL，如
https://token:x-oauth-basic@gitlab.example.com/...—— 这种写法会被提交到 Git，且新版 Composer 已弃用
用 gitlab-token 字段替代 http-basic？不推荐，GitLab 不认
有些文档提到 composer config --auth gitlab-token.gitlab.example.com your_token，但这会生成 {"gitlab-token": {"gitlab.example.com": "..."}} 结构，而 Composer 对 GitLab 认证只识别 http-basic 字段。该配置无效，Composer 完全忽略它。
必须用 http-basic，且 username 固定填 git（GitLab 强制要求），password 填 Personal Access Token（PAT）完整字符串，例如 glpat-xxxxxxxxxxxxxxxxxxxx。
- PAT 必须勾选
read_api和read_repository，缺一不可 - 不要用 deploy token 或 CI job token，它们不支持
http-basic认证流 - 如果 GitLab 实例启用了子路径（如
/gitlab），域名仍只写gitlab.example.com，不带路径
CI 环境下怎么安全注入 token？别硬编码，用变量 + composer config
GitLab CI 中不能把 token 明文写进 .gitlab-ci.yml，也不能靠 before_script echo 到 auth.json —— 权限和 JSON 格式极易出错。正确做法是用 CI 变量配合 composer config 命令动态写入：
before_script: - composer config --global --auth http-basic.$GITLAB_DOMAIN git $GITLAB_PAT
其中 $GITLAB_DOMAIN 和 $GITLAB_PAT 是预设的 CI 变量（Masked & Protected）。这样生成的 auth.json 位置正确、权限自动设为 600，且不污染项目代码。
- 确保
$GITLAB_DOMAIN和composer.json中仓库 URL 的 host 完全一致 - CI runner 镜像需含
openssh-client（即使走 HTTPS，某些旧版 Composer 也会调用 ssh 命令校验） - 若用 SSH 方式，
composer config不起作用 —— 改用ssh-agent加载私钥，且 deploy key 必须绑定到目标私有包所在仓库，不是当前项目
配置完怎么验证是否生效？别只看 composer install
运行 composer install 成功不代表认证真生效 —— 它可能从缓存拉取旧包。最准的验证方式是清缓存后强制重拉：
composer clear-cache composer update --dry-run
观察输出中是否出现 Cloning into '...' 或 Downloading ...；若仍有 Could not fetch 或弹出用户名密码提示，说明凭据未命中。
- 用
git ls-remote https://gitlab.example.com/group/pkg.git手动测试，看是否能列出 refs —— 这绕过 Composer，直检网络和认证链 - HTTPS 下若报 SSL 证书错误（尤其内网自签名），需额外执行
composer config --global cafile /path/to/cert.pem - SSH 方式下，
ssh -T git@gitlab.example.com返回Welcome to GitLab才算密钥链通
GitLab 私服集成的关键不在命令多复杂，而在域名、权限、token scope、文件位置这四点严丝合缝 —— 错一个，就静默失败。
