composer如何设置认证令牌访问私有包？（auth.json配置详解）

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%Composerauth.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 清一下。