auth.json用于Composer HTTP Basic认证，支持私有仓库访问；位置优先级为项目根目录→COMPOSER_HOME/auth.json→config.json内嵌；需精确匹配域名、避免提交至Git。
Composer 通过 auth.json 文件支持 HTTP Basic 认证，用于安全访问私有 Packagist 仓库、GitLab、GitHub（私有包）、自建 Satis/SatisPress 或其他需要用户名密码的 Composer 仓库。
auth.json 放在哪？优先级怎么算？
auth.json 可以放在多个位置，Composer 按以下顺序查找并合并（后加载的覆盖前一个同名配置）：
- 当前项目根目录下的
auth.json（最常用，适合单项目私有依赖） -
COMPOSER_HOME环境变量指定路径下的auth.json（默认是~/.composer/auth.json，全局生效） -
COMPOSER_HOME下的config.json中内嵌的http-basic配置（不推荐，可读性差）
建议：项目级私有包用项目根目录 auth.json；团队共享仓库用全局 ~/.composer/auth.json。
auth.json 基本结构与字段说明
核心是 http-basic 键，其下每个子项对应一个仓库域名，值为含 username 和 password 的对象：
{
"http-basic": {
"gitlab.example.com": {
"username": "alice",
"password": "token_or_password_here"
},
"repo.mycompany.com": {
"username": "deploy",
"password": "abc123def456"
}
}
}注意：
- 域名必须精确匹配仓库 URL 的 host 部分（不含协议和路径），例如 https://gitlab.example.com/api/v4/projects → 填 gitlab.example.com；
- password 可以是明文密码，但更推荐使用只读 API Token（如 GitLab Personal Access Token、GitHub Fine-grained Token），权限最小化；
- 不要将 auth.json 提交到 Git（加到 .gitignore），尤其不能出现在公开仓库中。
配合 composer.json 正确声明私有仓库
auth.json 只负责认证，还需在 composer.json 中声明仓库来源：
- 如果是私有 Packagist 兼容仓库（如 Satis、Private Packagist），添加
repositories：
"repositories": [
{
"type": "composer",
"url": "https://repo.mycompany.com"
}
]- 如果是 Git 仓库（GitHub/GitLab 私有库），可直接写 VCS 类型，Composer 会自动识别 host 并查
auth.json：
<pre class="brush:php;toolbar:false;">"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/group/private-package.git"
}
]只要 auth.json 中存在 <code>"gitlab.example.com" 条目，Composer 在克隆或获取元数据时就会自动带上 Basic Auth 头。
调试与常见问题
如果认证失败（报错如 401 Unauthorized 或 Failed to download ... Invalid credentials），按顺序检查：
- 运行
composer config --global --list | grep -i auth查看是否误配了全局凭据 - 确认
auth.json文件权限：避免被其他用户读取（Linux/macOS 上建议chmod 600 auth.json） - 用
curl -v -u user:pass https://repo.example.com/packages.json手动测试是否能通 - 注意某些 Git 服务商（如 GitLab）要求 token 放在
username字段、密码留空，或反向（取决于 API 版本），查阅对应文档
另外，Composer 2.2+ 支持 auth.json 加密（需配合 composer config --auth 命令），但日常开发中明文 + 合理权限控制已足够安全。
基本上就这些。auth.json 是 Composer 访问私有生态的钥匙，结构简单，但域名匹配和文件位置容易出错，配好一次，后续 install/update 就能自动走认证流程。
