解决Composer提示“Authentication required”时的凭证配置指南（auth.json）

苏承栈

2026-09-06 • 👁 0人浏览过

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. js on 文件该放哪儿？优先级怎么算？ 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..."
        }
    }
}

注意两点： PHP 8.5.5 PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。下载

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（

api

scope），用户名固定填

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 就当它是另一个服务，不会复用凭据。

相关文章