Composer私有包认证核心是避免将token硬编码在composer.json或提交auth.json；需严格匹配域名、正确使用COMPOSER_AUTH环境变量、区分vcs与composer类型仓库的认证配置，并确保token权限精准对齐。
Composer 用 token 认证私有包，核心就一条：别往 composer.json 里塞 token，也别手动改 auth.json 后提交到 Git —— 这两种做法在 2026 年仍是最常被踩的雷。
为什么 composer config http-basic 命令有时不生效
它确实会写入 auth.json，但生效前提是域名完全匹配。比如仓库 URL 是 https://gitlab.example.com/group/pkg.git，那配置时必须用 composer config http-basic.gitlab.example.com，填 gitlab.com 或 example.com 都白搭。
- 执行
composer config --list看输出里有没有对应域名的http-basic条目，没有就是没写对位置 - 如果用了自建 GitLab（带端口），比如
gitlab.example.com:8080，auth.json里 key 必须一模一样，少个端口都不认 -
composer config默认写项目级./auth.json，加--global才写进~/.config/composer/auth.json，CI 环境下后者更常见但要注意多项目隔离问题
COMPOSER_AUTH 环境变量怎么写才合法
这个变量值必须是完整、无换行、双引号包裹的 JSON 字符串，不是随便拼个 key=value 就行。Composer 1.10+ 开始原生支持，且优先级高于所有本地 auth.json 文件。
- 正确格式：
{"http-basic":{"gitlab.example.com":{"username":"token","password":"glpat-xxx"}}} - GitHub Packages 要用
github.com域名，GitLab CE 自建站必须用实际访问域名（不能简写） - GitHub Actions 中 Secret 存的就是上面那段字符串，不是只存 token；GitLab CI 里用
$CI_JOB_TOKEN替换占位符时，要确保替换后仍是合法 JSON - 别用
echo '{"http-basic":{...}}' > auth.json这类操作——CI 工作区残留文件可能被日志捕获
GitLab 私有包拉不到？大概率是 vcs 类型 + HTTP 认证没配全
当 composer.json 的 repositories 里 type 是 vcs，且 URL 是 HTTPS 地址时，Composer 底层会调用 git clone。这时候光配 http-basic 不够，因为 git 命令本身不读 Composer 的认证配置。
- 必须同时做两件事：在
auth.json或COMPOSER_AUTH里配好http-basic，并在composer.json里加"git_source": "https://oauth2:${GITLAB_TOKEN}@gitlab.example.com/" -
${GITLAB_TOKEN}要和 CI 环境变量名一致，GitLab CI 里常用$CI_JOB_TOKEN，需用sed提前替换 - 如果用的是 GitLab Package Registry（
type: "composer"），则只需http-basic，不需要git_source
自定义 HTTP 头（如 PRIVATE-TOKEN）只在 --prefer-source 下起作用
某些私有 Git 服务（Gitea、GitLab CE）要求 token 放在请求头里，而不是基础认证字段中。这种配置只能硬编码在 composer.json 的 repositories.options.http.headers 里，而且只对 source 模式生效。
- 示例配置：
"headers": {"private-token": "glpat-xxx"}，注意大小写和键名必须和服务端文档完全一致 - 默认
composer install优先走 dist（zip 包），此时 headers 被忽略；加--prefer-source才会触发 git clone 并带上 header - GitHub.com 和 GitLab.com 这类公开平台会绕过该配置，必须用自建实例域名才能生效
- 环境变量注入要用
${VAR}语法，不能用$VAR，否则解析失败
最易被忽略的一点：Token 权限必须和使用场景严格对齐。用 vcs 拉代码，只要 read_repository；走 GitLab Package Registry，则必须 read_package_registry —— 少一个 scope，403 就不会告诉你缺哪个。
