auth.json文件编码必须为UTF-8无BOM，因Composer对编码敏感，Windows记事本默认保存为UTF-8 with BOM或ANSI会导致JSON解析失败或静默跳过认证。
auth.json 文件编码必须是 UTF-8 无 BOM
Composer 读取 auth.json 时对编码极其敏感，Windows 上用记事本保存默认是 ANSI 或 UTF-8 with BOM，会导致解析失败，报错类似 JSON decode error: Syntax error 或静默跳过认证。
实操建议：
- 用 VS Code、Notepad++ 或 Sublime Text 打开
auth.json，确认右下角显示 “UTF-8”（不是 “UTF-8 with BOM”） - 在 VS Code 中：点击右下角编码 → 选择 “Save with Encoding” → 选 “UTF-8”
- 命令行快速验证：
file -i ~/.composer/auth.json（Linux/macOS）或Get-Content .\auth.json -Encoding UTF8 | ConvertTo-Json（PowerShell，仅作辅助）
auth.json 文件权限不能过于宽松（尤其 macOS/Linux）
Composer 默认拒绝读取权限过宽的 auth.json，比如 644 在某些版本会警告，666 或 755 直接报 Authentication is required 却不提示具体原因。
实操建议：
- 设为
600最稳妥：chmod 600 ~/.composer/auth.json - Windows 用户无需改权限，但需确认文件未被系统标记为“来自其他计算机”（右键属性 → 解除“安全”栏中的勾选）
- 若使用 Docker 或 CI 环境，检查挂载卷是否覆盖了原始权限，或用
docker run --user $(id -u):$(id -g)避免权限降级
凭证字段名写错或嵌套层级不对
常见错误是把 http-basic 写成 https-basic，或把域名拼错（如 packagist.org 写成 https://packagist.org），又或者把 token 放在 github.com 下却没加 token 字段名。
正确结构示例（私有 GitLab 仓库）：
{
"http-basic": {
"gitlab.example.com": {
"username": "gitlab-ci-token",
"password": "your_personal_access_token"
}
},
"github-oauth": {
"github.com": "your_github_token"
}
}
关键点：
-
http-basic下的 key 是纯域名（不含协议、路径、端口） -
github-oauth的值是字符串 token，不是对象 - 私有 Packagist 类型仓库若用 token 认证，应放在
token字段，不是password
Composer 版本差异导致 auth.json 加载逻辑不同
2.2+ 版本开始强制校验 auth.json 权限和编码，而 1.x 对部分错误更宽容；同时，2.5.0 起支持 auth.json 放在项目根目录（优先于全局），容易因路径混淆导致预期外的配置未生效。
排查建议：
- 运行
composer config --global --list | grep auth确认 Composer 正在读哪个位置的文件 - 临时重命名全局
auth.json，把配置挪到项目下./auth.json并执行composer config --auth http-basic.gitlab.example.com ...测试是否生效 - 升级前先备份：旧版可能把 token 存在
~/.composer/config.json的config字段里，新版已弃用该方式
实际遇到最隐蔽的问题，往往是编辑器自动加了 BOM + 权限设成 644，两者叠加后 Composer 不报具体错误，只回退到匿名访问——这时候连 composer diagnose 都不会提示 auth.json 异常。
