Composer提示Authentication required是因为私有仓库凭证缺失或配置错误；auth.json应置于项目根目录或用户主目录，优先级为COMPOSER_AUTH环境变量＞项目级＞全局；GitHub Packages需read:packages权限及正确域名匹配。
Composer 提示 Authentication required，说明它正尝试访问需要身份验证的私有仓库（如 GitHub Packages、GitLab Registry、Packagist.org 的私有包，或自建 Satis/SatisPress），但没找到有效凭证。这不是网络问题，也不是权限未开，而是 auth.json 没配对、没放对位置、或 token 权限不足。
auth.json 文件该放哪儿？优先级怎么算？
Composer 会按顺序查找 auth.json，找到第一个就用，后面的被忽略：
-
COMPOSER_AUTH环境变量（值为 JSON 字符串，需 URL 编码）——最高优先级，适合 CI/CD - 当前项目根目录下的
auth.json（即和composer.json同级）——只影响本项目，最安全 - 用户主目录下的
~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows）——全局生效，慎用
本地开发建议用项目级 auth.json；CI 环境推荐用 COMPOSER_AUTH 注入，避免文件泄漏。
GitHub Packages 场景下 token 怎么配才有效？
GitHub Packages 要求 token 至少有 read:packages（安装）或 write:packages（发布），且必须启用 workflow（如果用于 Actions）。仅 repo 权限不够。
配置示例（auth.json 内容）：
{
"github-oauth": {
"github.com": "ghp_xxx..."
},
"http-basic": {
"npm.pkg.github.com": {
"username": "your-github-username",
"password": "ghp_xxx..."
}
}
}
注意两点：
-
github-oauth仅用于 GitHub API 访问（如获取私有 repo 的 composer.json），不用于 packages 域名 -
npm.pkg.github.com是 GitHub Packages 的 npm registry 地址；若你用的是 Composer registry（https://composer.pkg.github.com/owner），应填该完整域名到http-basic键中
GitLab 或私有 Packagist 如何填 domain 和凭据？
GitLab 的 Composer registry 地址形如 https://gitlab.example.com/api/v4/groups/my-group/-/packages/composer，但 auth.json 中的 domain 必须是基础主机名，不含路径：
{
"http-basic": {
"gitlab.example.com": {
"username": "oauth2",
"password": "glpat-xxx..."
}
}
}
关键点：
- domain 取
parse_url($registry_url, PHP_URL_HOST)的结果，不是完整 URL - GitLab 推荐用 Personal Access Token（
apiscope），用户名固定填oauth2（否则 401） - 自建 Satis 需确认是否启用了 HTTP Basic Auth；若用 Nginx 做 auth，domain 就是 Satis 域名，凭据由你自行设定
为什么改了 auth.json 还报错？常见失效原因
配完不生效，多数不是语法错，而是这些细节卡住：
-
auth.json文件权限太松（如 777）：Composer 会拒绝读取，Linux/macOS 下确保权限 ≤ 600 - token 已过期或被撤回：GitHub/GitLab token 不支持“永久”，需定期轮换
- Composer 缓存了旧响应：运行
composer clear-cache再试 - 使用了错误的 registry URL：在
composer.json的repositories里检查url是否与auth.json中的 domain 匹配（协议、端口、子域都要一致） - PHP CLI 和 Web 服务器用的不是同一份
auth.json：Web 环境常走全局路径，CLI 可能走项目路径，需分别确认
最易被忽略的是 domain 匹配粒度——哪怕多一个 www. 或端口号不同，Composer 就当它是另一个服务，不会复用凭据。
