Composer如何存储认证信息_auth.json配置要点-composer-PHP中文网

auth.json 必须存于三个指定路径之一：项目根目录（./auth.json）、composer_home 目录下（如 ~/.composer/auth.json）或系统级配置目录，按顺序查找且不合并；key 必须精确匹配仓库 host（不含协议/路径），推荐用 composer config 命令写入并设 .gitignore；ci/cd 中应使用 composer_auth 环境变量传递认证信息。

composer如何存储认证信息_auth.json配置要点

Composer 认证信息必须存进 auth.json，不能写在 composer.json 里，否则会泄露密码或令牌。

auth.json 文件该放哪儿？路径和优先级要搞清

Composer 只在三个位置找 auth.json，按顺序读取，**先找到就停，不会合并**：

当前项目根目录（./auth.json）→ 仅对本项目生效
COMPOSER_HOME 目录下（Linux/macOS 通常是 ~/.composer/auth.json 或 ~/.config/composer/auth.json；Windows 是 %APPDATA%\Composer\auth.json）→ 全局生效
系统级配置目录（极少用，一般不用管）

常见错误是把文件扔错地方：比如在项目里建了 ./composer/auth.json，但 Composer 只认 ./auth.json；或者改了全局路径却没确认 COMPOSER_HOME 实际指向哪——可用 composer config --global --list | grep config-home 查。

http-basic 的 key 必须精确匹配仓库域名

填错 key 是“Authentication failed”最常见原因。key 不是完整 URL，也不是组织名，而是 仓库地址的 host 部分，不含协议、端口（除非显式指定）、路径：

仓库 URL 是 https://packages.myorg.com → key 是 "packages.myorg.com"
仓库 URL 是 https://repo.internal:8080/api/v1 → key 是 "repo.internal:8080"（带端口）
仓库 URL 是 https://gitlab.company.com/group/pkg → key 是 "gitlab.company.com"
填 "myorg.com"、"https://packages.myorg.com" 或 "packages.myorg.com/api" 都无效

如果私有源用了自签名证书或反向代理，还要确保域名解析和 TLS 证书 Subject Alt Name（SAN）也匹配这个 key。

用命令行写入比手写更安全可靠

手动编辑 auth.json 容易格式出错（比如多逗号、少引号），也难控制权限。推荐一律用 composer config 命令：

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

项目级（只影响当前项目）：composer config http-basic.packages.example.com alice topsecret123
全局级（所有项目都用）：composer config --global http-basic.packages.example.com alice topsecret123
GitLab 个人访问令牌（推荐）：composer config --global gitlab-token.gitlab.com glpat-xxxxxx
GitHub OAuth Token：composer config --global github-oauth.github.com xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

执行后 Composer 自动创建文件、写入 JSON、设好权限（Linux/macOS 下默认 600）。你只要确认它没被 git add 进仓库就行——务必加进 .gitignore。

CI/CD 环境别写文件，用 COMPOSER_AUTH 环境变量

在 GitHub Actions、GitLab CI 等环境里，硬生成 auth.json 文件风险高（可能残留、日志泄露）。应该用 COMPOSER_AUTH 环境变量传入 JSON 字符串：

{"http-basic": {"packages.example.com": {"username": "alice", "password": "topsecret123"}}}

例如 GitHub Actions 中：

把令牌存为 Secret（如 PRIVATE_REPO_TOKEN）
在 job step 里用 env: 注入：COMPOSER_AUTH: '{ "http-basic": { "packages.example.com": { "username": "alice", "password": "${{ secrets.PRIVATE_REPO_TOKEN }}" } } }'

注意：JSON 字符串必须是单行、双引号、转义正确；COMPOSER_AUTH 优先级高于磁盘上的 auth.json，且只在当前进程有效。

最容易被忽略的是域名匹配精度和权限控制——哪怕 token 正确，host 写错一个字符，或 auth.json 被误提交到 Git，整个流程就会静默失败或暴露凭证。