auth.json 应放项目根目录（最高优先级）或用户主目录（如~/.composer/auth.json），不可放子目录或vendor；需确保权限严格（如644）、json合法、域名与仓库url完全匹配，且github pat须含repo等必要权限。
auth.json 文件该放在哪里才生效
Composer 查找 auth.json 的路径有优先级：当前项目根目录下的 auth.json > 当前用户主目录的 auth.json（如 ~/.composer/auth.json 或 ~/composer/auth.json，取决于 Composer 版本）> 全局配置目录（COMPOSER_HOME 环境变量指定路径）。项目级配置优先级最高，适合私有包认证；全局配置适合统一管理多个项目的通用凭证。
常见错误是把 auth.json 放在子目录或 vendor 下——Composer 完全不会读取。也别用 composer config --global 写入后手动去改文件，容易格式错乱。
- 私有 Git 仓库（如 GitHub private repo、GitLab 私有组）建议用项目级
auth.json，避免泄露到团队其他成员机器 - 使用 Satis 或 Private Packagist 时，通常走全局配置更稳妥
- Windows 用户注意：
COMPOSER_HOME默认是%USERPROFILE%\AppData\Roaming\Composer，不是%USERPROFILE%\composer
GitHub Personal Access Token 怎么填才不被拒绝
GitHub 已停用密码认证，必须用 Personal Access Token（PAT）。但不是所有 token 都能用：Composer 要求 token 至少带 repo 权限（读私有仓库）、read:packages（如果用 GitHub Packages）、delete:packages（若需删包）。只勾 public_repo 会导致 404 Not Found 或 403 Forbidden 错误，尤其访问私有组织仓库时。
auth.json 中写法要严格：
{
"github-oauth": {
"github.com": "ghp_xxx..."
}
}
- 域名必须是
github.com，不是api.github.com或带端口的地址 - token 值不能加引号外的空格，JSON 格式必须合法（可用
composer validate检查） - GitHub Enterprise 用户需用实际域名，如
"ghe.example.com": "xxx" - token 泄露风险高，务必禁止将
auth.json提交进 Git——加到.gitignore是底线
GitLab 和 Bitbucket 的 auth.json 写法差异
GitLab 不走 github-oauth 字段，而是用 http-basic + 基础认证。Bitbucket 同理，但用户名必须是账号邮箱或 API token（v2 token 推荐），不能是普通登录密码。
GitLab 示例（访问私有 Group 下的 Composer 包）：
{
"http-basic": {
"gitlab.example.com": {
"username": "gitlab-ci-token",
"password": "GLPAT-xxx..."
}
}
}
-
username用gitlab-ci-token是为了兼容 CI 场景，本地开发可填真实用户名 - Bitbucket Cloud v2 token 必须开启
repository:read权限；Bitbucket Server（即自建 Stash）需用 Basic Auth，密码字段填 App Password - 所有 HTTP 域名必须和
composer.json中仓库url的 host 完全一致（含子域、端口），否则认证失败且无明确提示
为什么 composer install 时不读 auth.json 或报 401
最常被忽略的是权限问题：Linux/macOS 下，如果 auth.json 所在目录或文件权限太宽松（如 777 或组/其他用户可读），Composer 会直接跳过加载并静默失败——这是安全策略，不是 bug。
- 检查权限：
ls -l auth.json，确保不是 group/o 可写（-rw-r--r--或更严格） - 运行
composer diagnose，它会明确提示 “Authentication file is not readable” - CI 环境（如 GitHub Actions）中，
auth.json必须通过secrets注入，且不能用echo直接写入（易暴露），推荐用setup-phpaction 自动配置 - 某些私有仓库启用了 2FA，此时 PAT 必须额外启用
write:packages才能 push，但 install 只需read权限
auth.json 的坑不在语法，而在上下文：路径、权限、token 权限、域名匹配、环境隔离——漏掉任意一环，Composer 就当它不存在。
