私有源必须显式声明在项目根目录composer.json的repositories数组中,且需满足type正确、url末尾带斜杠、packagist:false独立置末等硬性条件,否则Composer不会查找。

私有源必须显式写在项目级 composer.json 的 repositories 数组里
Composer 不会自动发现或继承私有源,哪怕你搭好了 Satis、配置了全局 auth.json、甚至在包自己的 composer.json 里写了源——全无效。生效的唯一位置是:你要运行 composer require 或 composer install 的那个项目的根目录下的 composer.json。
常见错误现象:
-
Could not find package xxx/yyy,但你知道它明明在私有源里 - 执行
composer config --list | grep repositories看到空输出,误以为“没配”,其实根本不是 config 命令管的事
正确写法示例(注意格式细节):
{
"repositories": [
{
"type": "composer",
"url": "https://pkgs.internal/"
},
{
"packagist": false
}
]
}
关键点:
-
"packagist": false必须是独立对象,不能合并进前面的源里 - 顺序不能错:私有源在前,
"packagist": false在后;否则 Composer 查完私有源失败,仍会 fallback 到 packagist.org -
url值末尾必须带/,比如"https://pkgs.internal/",少斜杠会拼成https://pkgs.internalpackages.json - 不能写成对象形式:
"repositories": {"my-repo": {...}}是非法 JSON,直接报错
auth.json 权限和域名必须一字不差,否则静默跳过认证
即使 composer.json 配对了,私有源也返回 401,大概率是 auth.json 没被读取——不是报错,是假装没这回事。
必须满足三个硬性条件:
- 文件权限必须是
600(Linux/macOS):ls -l ~/.composer/auth.json应显示-rw------- - 域名 key 必须与仓库 URL 的
host:port完全一致,包括大小写、端口、无协议头、无路径。例如源地址是https://gitlab.internal:8080/api/v4/projects/123/packages/composer,key 就得是"gitlab.internal:8080" - 文件编码必须是 UTF-8 无 BOM:
file -i ~/.composer/auth.json输出应含charset=utf-8;若显示utf-8-with-bom,用 VS Code 以“UTF-8 无 BOM”保存
验证是否生效:
- 运行
composer config --global --list | grep -E "(http-basic|github-oauth|gitlab-token)",有输出才说明凭据已注册 - 用
curl -I https://gitlab.internal:8080/确认网络可达,再比对 key 是否完全一致
认证类型必须匹配私有源后端,用错就等于没配
HTTP 基础认证(Satis、Nexus、GitLab Packages API)、GitHub OAuth、GitLab Token 是三套互不兼容的机制。填错类型,Composer 根本不会尝试发送凭据。
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
判断依据:
- 如果你的私有源是自建 Satis 或 Nexus,用
http-basic - 如果是 GitHub 私有仓库,用
github-oauth - 如果是 GitLab 实例(非 GitHub),优先用
gitlab-token,基础认证则用http-basic
配置方式务必用 composer config 命令生成,避免手写 JSON 出错:
- GitLab 基础认证:
composer config --global http-basic.gitlab.internal username your-password - GitHub OAuth:
composer config --global github-oauth.github.com abcdef0123456789
错误示范:
- 对 GitLab 写
github-oauth→ 凭据永不触发 - 在
http-basic下把 token 当 password 填 → 401
项目级 auth.json 放错位置等于没配
项目级凭据只在特定场景有用(比如 CI/CD 中不同项目用不同 token),但它必须严格放在项目根目录,且和 composer.json 同级。
Composer 只查三个位置,按优先级从高到低:
- 当前项目根目录下的
auth.json -
COMPOSER_HOME目录(通常是~/.composer/auth.json) - 系统级目录(极少用)
容易踩的坑:
- 把
auth.json放进vendor/、src/或子目录 → 彻底失效 - CI 中用项目级
auth.json却没加进.gitignore→ 密钥泄露 - Windows 用户误查
%APPDATA%\Composer\auth.json时被组策略拦截,需手动确认文件存在且可读
复杂点在于:白名单本身不校验源是否真实可用,只控制“允许 Composer 去连哪个地址”。真正卡住的往往是网络通路、Web 服务 MIME 类型、ZIP 包路径权限这些底层细节——它们不出错,repositories 和 auth.json 再对也没用。

















