auth.json是私有包安装失败时的必查点，必须按项目根目录→$COMPOSER_HOME/auth.json→COMPOSER_AUTH环境变量顺序放置，域名须与请求主机名完全一致，且禁止提交至Git或写入composer.json。
auth.json 不是可选项，而是私有包安装失败时的必查点；它不参与 Git 版本控制，也不能写进 composer.json，否则等于把密码提交到仓库。
auth.json 放哪儿才生效
Composer 按固定顺序查找 auth.json，找到第一个就停：项目根目录 → $COMPOSER_HOME/auth.json（通常是 ~/.composer/auth.json 或 %APPDATA%\Composer\auth.json）→ 环境变量 COMPOSER_AUTH。路径错、放错位置，等于没配。
- 项目级配置优先级最高，适合每个项目用不同 token 的场景，记得加
/auth.json到.gitignore - 全局配置适合个人开发机统一管理 GitHub/GitLab token，但不能用于团队共享凭据（比如 CI 机器上不该有你的私人 token）
- 别把
auth.json放在vendor/、src/或子目录里——Composer 完全不读 - Windows 用户注意：
%APPDATA%\Composer\auth.json是默认路径，不是%USERPROFILE%\.composer\auth.json
http-basic 域名必须和仓库 URL 主机名完全一致
报错 Could not fetch https://packages.example.com/packages.json, please review your auth config: packages.example.com？那 auth.json 里 key 就得是 "packages.example.com"，少一个字符、多一个 www.、带端口或协议都不行。
- 仓库 URL 是
https://api.internal.company:8080/v2→ key 填"api.internal.company:8080"（端口要带上） - 仓库 URL 是
https://gitlab.example.org/api/v4/groups/mygroup/-/packages/composer→ key 填"gitlab.example.org"（只取主机名，路径和协议前缀忽略） - 如果用了反向代理，域名按实际请求发出的 Host 头来填，不是你浏览器里输的地址
- 运行
composer config --global --list | grep http-basic可快速确认是否读到了配置
github-oauth 和 gitlab-token 字段不能混进 http-basic
GitHub 私有库、GitLab Package Registry 这类平台有自己的认证机制，http-basic 字段对它们无效。填错位置，token 就不会被自动带上。
- GitHub 的 Personal Access Token 必须放在
github-oauth下，key 是"github.com"（不能是"api.github.com"） - GitLab 的 PAT 要用
gitlab-token字段，key 是 GitLab 实例的域名（如"gitlab.example.com"），且 token 至少要有read_api权限 -
http-basic只适用于私有 Packagist（如 Satis、Private Packagist）、自建 Composer repo 等走 HTTP Basic Auth 的服务 - 手动编辑
auth.json时，字段名拼错（比如写成github_oauth或gitlabToken）会导致整个字段被忽略
用命令行写入比手写更安全
手写 JSON 容易多逗号、少引号、用单引号，导致格式非法；composer config 命令会自动校验并格式化，推荐所有非 CI 场景都用它。
- 项目级写入：
composer config http-basic.packages.example.com myuser mytoken（生成./auth.json） - 全局写入：
composer config --global http-basic.packages.example.com myuser mytoken（写入$COMPOSER_HOME/auth.json） - GitHub token 必须手动加：
composer config --global github-oauth.github.com ghp_xxx - 写完立刻执行
composer clear-cache，否则旧缓存可能掩盖配置生效状态
最容易被跳过的其实是权限检查：Linux/macOS 上 auth.json 文件权限不能宽于 600，否则 Composer 会静默忽略；Windows 上则要注意杀毒软件偶尔会锁住文件导致写入失败。真遇到“配了还是 401”，先看文件权限和报错里提示的域名是否一字不差。
