auth.json应放项目根目录或$COMPOSER_HOME（如~/.composer/auth.json），权限设为600；优先级顺序为：COMPOSER_AUTH环境变量＞项目级auth.json＞全局auth.json；域名必须完全匹配（含端口、不含协议）。
Composer 报 authentication required 错误，90% 不是密码输错了，而是 auth.json 里域名没对上、放错位置、或被更高优先级的配置覆盖了。
auth.json 文件该放哪？优先级怎么算？
Composer 查找 auth.json 是「找到就停」，顺序固定：
- 当前项目根目录下的
auth.json（最高优先级，只影响本项目） -
$COMPOSER_HOME/auth.json（Linux/macOS 默认是~/.composer/auth.json，Windows 是%APPDATA%\Composer\auth.json） - 系统级路径（极少用，基本不用管）
注意：COMPOSER_AUTH 环境变量优先级比所有 auth.json 都高 —— 只要它存在且匹配，后面文件全跳过。调试时可加 --no-auth 强制绕过，确认是不是认证环节出问题。
http-basic 域名必须一字不差匹配请求地址
报错里出现的域名，就是你要填进 auth.json 的 key。比如 Composer 提示：
Could not fetch https://packages.internal.company:8443/packages.json
那 auth.json 里就得写：
{ "http-basic": { "packages.internal.company:8443": { "username": "...", "password": "..." } } }
常见错误包括：
- 漏掉端口（
packages.internal.company≠packages.internal.company:8443） - 协议前缀混入（
https://packages.internal.company是错的，key 不能带https://） - 路径部分参与匹配（
https://api.example.com/v1的 key 应是api.example.com，不是api.example.com/v1） - www 前缀不一致（
www.repo.com和repo.com是两个 host）
别手写 auth.json，用 composer config 命令生成
手动编辑容易格式出错、引号漏转义、权限不对。推荐用命令行写入：
- 项目级（写入当前目录
auth.json）：composer config http-basic.packages.example.com user token - 全局级（写入
$COMPOSER_HOME/auth.json）：composer config --global http-basic.packages.example.com user token
这条命令会自动处理 JSON 合法性、文件创建、权限设置（Linux/macOS 下默认设为 600）。如果已存在同域名配置，会直接覆盖，不会叠加或报错。
GitHub/GitLab 私有包不能塞进 http-basic
GitHub 私有仓库必须用 github-oauth 字段，值是 Personal Access Token（至少带 read:packages 或 repo 权限）；GitLab 必须用 gitlab-token 字段，值是 glpat-xxx 格式的 token。
填错字段会导致静默失败：比如把 GitHub token 塞进 http-basic.github.com，Composer 不报错，但拉不到私有 repo —— 因为 GitHub API 不认 Basic Auth。
另外，auth.json 绝对不能提交进 Git。检查 .gitignore 是否含 /auth.json；CI 场景应改用环境变量 + composer config 动态注入，而不是传文件。
