auth.json 生效位置按优先级依次为：composer_auth 环境变量、项目根目录、用户主目录；github 需配置 github-oauth 与含 repo 权限的 classic pat；gitlab 等须用 http-basic 且域名严格匹配；401 错误需检查缓存、锁文件、nginx 头透传及 git 凭据助手。
auth.json 放哪儿才生效？
Composer 只在特定位置查找 auth.json，顺序错了就白配。它按优先级从高到低依次检查：
-
COMPOSER_AUTH环境变量（JSON 字符串） - 当前项目根目录下的
auth.json - 用户主目录的
~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows）
项目级配置最安全——只影响当前项目，不会污染全局；但 CI/CD 里常靠环境变量注入，避免把令牌写进 Git。
GitHub Personal Access Token 怎么填？
GitHub 私有仓库需要的是 github-oauth 配置，不是用户名密码。Token 必须带 repo 权限（如果是组织私仓，还需 read:org）。
正确写法：
{
"github-oauth": {
"github.com": "<code>ghp_xxx...</code>"
}
}
常见错误：
- 误填成 GitHub 账号密码（已不支持）
- Token 权限不足，报错
Could not fetch https://api.github.com/... 404或401 - 用了 GitHub App token 或 fine-grained token 却没配
github-app段（目前 Composer 原生只认 classic PAT）
GitLab 和私有 Packagist 怎么设域名和令牌？
GitLab、Bitbucket、自建 Satis/SatisPress 都走 http-basic，但必须严格匹配仓库域名。
比如 GitLab 实例在 gitlab.example.com，且包地址是 https://gitlab.example.com/group/pkg.git，就得这样写：
{
"http-basic": {
"gitlab.example.com": {
"username": "<code>your_username</code>",
"password": "<code>your_personal_access_token</code>"
}
}
}
注意点：
- 域名必须和
composer.json里repositories的 URL 主机名完全一致（gitlab.example.com≠https://gitlab.example.com） - GitLab 的 password 字段填的是 Personal Access Token，不是密码；Token 权限需含
read_repository - 自建 Packagist 若启用了 Basic Auth，也走同一套
http-basic，填管理后台给的账号密码即可
为什么 composer update 还是 401？
认证失败往往不是配置错，而是缓存或协议层干扰。
排查步骤：
- 运行
composer config --global --list | grep auth确认全局配置没覆盖项目配置 - 删掉
vendor/和composer.lock，再composer install（update 可能复用旧 lock 里的元数据） - 加
-v参数看详细请求：如果看到GET https://api.github.com/repos/xxx/xxx返回 401，说明 OAuth 失效；如果看到GET https://gitlab.example.com/group/pkg.git重定向到登录页，说明http-basic域名对不上 - 私有 Packagist 后端若用 Nginx，确认没误删
Authorization请求头（需显式透传：proxy_pass_request_headers on;）
最易忽略的是：Git 本身也会读 ~/.gitconfig 里的 credential helper，如果它缓存了错误凭据，Composer 走 HTTPS 克隆时可能被它劫持——此时要 git credential reject 清一下。
