Composer读auth.json需严格校验路径、权限、字段名、域名四要素，任一错误即静默跳过；查找顺序为：项目根目录./auth.json→用户主目录~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows）→COMPOSER_AUTH环境变量。
Composer 读 auth.json 不是“写了就能用”，而是严格按路径、权限、字段名、域名四重校验——任一环节错，就静默跳过，不报错也不提示。
auth.json 放哪儿 Composer 才认
它只在三个位置找，且找到第一个就停：./auth.json（项目根目录）→ ~/.composer/auth.json（Linux/macOS）或 %APPDATA%\Composer\auth.json（Windows）→ 环境变量 COMPOSER_AUTH。放在 vendor/、src/ 或子目录下完全无效。
常见踩坑点：
- CI 环境误把
auth.json提交进项目，以为放根目录就全局生效——其实只作用于当前项目，且 CI 常以www-data等非登录用户运行，权限不匹配直接忽略 - Windows 上写成
C:\Users\Name\.composer\auth.json，但实际应是%APPDATA%\Composer\auth.json（通常是C:\Users\Name\AppData\Roaming\Composer\auth.json） - Linux/macOS 下全局
auth.json权限 >600（比如 644），Composer 会静默跳过，不警告
github-oauth、gitlab-token、http-basic 字段名不能拼错
顶层键只有三个合法值：github-oauth、gitlab-token、http-basic（gitlab-oauth、token、github_oauth 全部被忽略，且不报错）。
不同场景必须用对字段：
- GitHub 私有仓库 → 必须用
github-oauth，key 是"github.com"（哪怕你用 GitHub Enterprise，也得填对应实例域名，如"gh.example.com"） - GitLab 私有仓库（vcs 类型）→ 必须用
gitlab-token，key 是 GitLab 实例的纯 host（如"gitlab.example.com"，不含协议、路径；若带端口，如"gitlab.example.com:8080"，key 也得带端口） - 私有 Packagist（Satis、Private Packagist）、Nexus/Artifactory Composer repo → 只能用
http-basic，且username字段常填 token，password留空（这是它们对 Basic Auth 的实现方式）
域名 key 必须和请求 URL 的 host 完全一致
不是“看起来像就行”，而是逐字符比对：带 www 要带 www，带端口要带端口，大小写敏感，协议和路径一律不参与匹配。
错误示例：
-
{"https://gitlab.example.com": {}}→ 协议前缀导致失效 -
{"gitlab.example.com/api/v4": {}}→ 路径部分被当作域名一部分，不匹配 - 仓库 URL 是
https://repo.example.com:8443/packages.json，但auth.json里写的是"repo.example.com"→ 缺少:8443，不生效
验证是否命中：运行 composer config --list | grep http-basic，看输出里有没有你期望的域名条目。
CI 环境别碰 auth.json 文件，用 COMPOSER_AUTH
在 GitHub Actions、GitLab CI 等环境中，硬写 auth.json 文件风险极高（可能残留工作区、日志泄露、权限混用）。正确做法是通过环境变量注入：
-
COMPOSER_AUTH值必须是合法 JSON 字符串，例如：{"http-basic":{"repo.example.com":{"username":"token","password":"abc123"}}} - GitHub Actions 中设为 Secret：
COMPOSER_AUTH: ${{ secrets.COMPOSER_AUTH }}，Secret 内容就是上面那段字符串 - GitLab CI 若用 vcs 类型仓库（如
"url": "https://gitlab.example.com/group/pkg.git"），光配http-basic不够，还得在composer.json里加"git_source": "https://oauth2:${CI_JOB_TOKEN}@gitlab.example.com/"，并用sed提前替换占位符
最易被忽略的一点：GitLab 的 Personal Access Token 必须同时开启 read_api 和 read_repository 权限——前者用于查项目元数据，后者用于 git clone --mirror，缺一不可。Deploy Token、CI_JOB_TOKEN、OAuth App Token 全部不支持 API 调用，第一步就失败。
