Composer需授权信息以访问私有仓库或限流API；auth.json按项目根目录→COMPOSER_HOME→系统级顺序查找，推荐放项目根目录并加入.gitignore；GitHub须用PAT填入github-oauth字段，私有Packagist等则用http-basic字段且域名须完全匹配。
Composer 需要授权信息，是因为它要访问私有仓库或限流的第三方服务（比如 GitHub 的 API），不配 auth.json 就会报 401 Unauthorized 或 API rate limit exceeded。
auth.json 放哪？优先级怎么算
Composer 查找 auth.json 有固定顺序：当前项目根目录 → COMPOSER_HOME 目录（通常是 ~/.composer/ 或 %APPDATA%\Composer\）→ 系统级位置（极少用）。推荐放在项目根目录，方便团队共享；若含敏感 token，记得加进 .gitignore。
- 项目级：直接放
./auth.json，只影响当前项目 - 用户级：放
~/.composer/auth.json，所有项目都继承（适合个人常用 token） - 环境变量
COMPOSER_HOME被覆盖时，路径会变，可用composer config --global home确认
GitHub Token 怎么写进 auth.json
GitHub 从 2021 年起禁用密码认证，必须用 Personal Access Token（PAT）。Token 权限至少勾选 repo（私有库）或 public_repo（仅公开库），否则仍会失败。
{
"github-oauth": {
"github.com": "ghp_xxx..."
}
}
- Token 必须是未过期、未被撤销的；可在
https://github.com/settings/tokens管理 - 不要用
ghp_开头的 token 访问 github.com 以外的域名（比如 gitlab.com），会报invalid grant - 如果同时用 GitHub 和 GitLab，
auth.json中需分别写github-oauth和gitlab-token字段
私有 Packagist 或自建 Satis 怎么配 HTTP Basic Auth
这类服务通常走 HTTP Basic 认证，不是 OAuth。不能塞进 github-oauth，得用 http-basic 字段，且域名必须和 repositories 中定义的 URL 主机名完全一致（注意带不带 www、协议、端口）。
{
"http-basic": {
"packages.example.com": {
"username": "deploy",
"password": "xxx"
}
}
}
- 密码明文存本地，务必限制文件权限：
chmod 600 auth.json - 如果仓库 URL 是
https://packages.example.com:8443，http-basic的 key 必须写成packages.example.com:8443，少一个字符都不行 - 某些企业镜像（如 Nexus）返回 403 而非 401，大概率是用户名/密码错，或账号没被授予对应仓库的 read 权限
最容易漏的是域名拼写和协议一致性——https://gitlab.example.org 和 gitlab.example.org 在 Composer 看来是两个不同 host；token 过期、权限不足、文件权限太宽，这三类问题占了实际报错的八成以上。
