私有包require失败主因是repositories配置非法或未生效:type拼错、url格式错误(如vcs缺.git、composer源末尾无/)、未显式禁用packagist.org,或auth.json权限/路径不正确;应运行composer diagnose定位解析错误。

私有包 require 失败、报 Could not find package,90% 不是 Git 仓库连不上,而是 Composer 根本没去你的私有源查——源没生效、顺序错、packagist.org 没关严,或配置字段本身非法。
检查 repositories 数组是否合法且位置正确
Composer 只读项目根目录 composer.json 中的 repositories 字段,且它必须是 JSON 数组(不是对象),每项必须含 type 和 url:
-
type只能是"vcs"、"composer"或"path";写成"git"、"compsoer"(拼错)会整条跳过 - VCS 类型(如 GitLab)的
url必须是可git clone的地址,结尾带.git(如https://gitlab.example.com/myorg/utils.git),不能是网页链接或带#main片段 - Composer 类型源(如 Satis)的
url必须以/结尾,且返回 HTTP 200 + 含packages键的 JSON(路径如https://pkg.myorg.com/) - 别把私有源写进包自己的
composer.json—— 它对安装它的项目完全无效
确认 packagist.org 是否被显式禁用
只要 repositories 数组里没写 {"packagist.org": false},Composer 就永远先查官方源,你的私有源再靠前也白搭。这条必须是独立对象,放在数组末尾:
"repositories": [
{"type": "composer", "url": "https://pkg.myorg.com/"},
{"packagist.org": false}
]
- 写成
"packagist": false或"packagist.com": false会被静默忽略 - 不能嵌套在其他仓库对象里(如
{"type":"composer","url":"...","packagist.org":false}) - 运行
composer config repositories,输出里如果还出现https://repo.packagist.org,说明没关成功
验证私有源是否真被访问
composer search 不走你配的私有源,它只查 Packagist 全局索引,所以搜得到 ≠ 装得上。真正验证方式是:
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
- 运行
composer require myorg/utils:dev-main -vvv,看日志中是否出现你的私有源域名(如GET https://pkg.myorg.com/p/myorg/utils.json) - 如果日志里全是
packagist.org或直接报错invalid repository,说明配置未通过解析 - 此时立刻跑
composer diagnose,它会明确指出哪一行repositories解析失败(比如 URL 缺.git、type拼错) - VCS 包不会出现在 provider 索引里,
require时才触发元数据拉取;所以首次安装失败,往往卡在Reading composer.json of myorg/utils (dev-main)这一步
认证与 auth.json 是唯一合法路径
私有 Git 仓库(GitLab/GitHub)报 401 Unauthorized 或 404,几乎从不是密码错,而是凭据根本没加载:
- 凭证只能通过
auth.json提供,且文件权限必须是600(chmod 600 ~/.composer/auth.json) - 全局
auth.json路径为~/.composer/auth.json;项目级则放项目根目录,但仅限path类型源 - URL 域名必须和
auth.json里的host完全一致(gitlab.example.com≠https://gitlab.example.com) - 别把 token 写进
composer.json或 URL(如https://token:x-oauth-basic@gitlab.example.com/...),这既不安全又易失效
最容易被忽略的是:Composer 2.2+ 已废弃 repo.packagist 键名,且 repositories 数组一旦存在,全局镜像配置就彻底失效——你以为配了阿里云镜像,其实项目级配置让它完全没机会生效。










