“Package not found”是因Composer未访问私有仓库:repositories须在顶层且type为"vcs",url需合法git地址,auth.json路径权限须正确,包名与分支须严格匹配私有库composer.json,且必须显式禁用packagist.org。

“Package not found”不是包丢了,是 Composer 根本没去你的私有仓库找——90% 的情况,repositories 配置无效、认证没生效,或包名/分支写错,它就安静跳过,不报错也不提示。
repositories 必须写在项目 composer.json 顶层,且每项 type 必须为 "vcs"
Composer 只读当前项目的 composer.json 最外层 repositories 数组,其他位置(比如嵌在 config 或子对象里)会被完全忽略。
-
type只能是"vcs",写成"git"、"github"、"gitlab"或留空,整条配置静默失效 -
url必须是可直接git clone的地址:HTTPS 格式如https://gitlab.example.com/acme/utils.git,SSH 格式如git@gitlab.example.com:acme/utils.git - 结尾带
.git是安全的;但加路径(如/acme/utils.git#main)、带查询参数、或写成网页 URL(如https://gitlab.example.com/acme/utils),都会导致元数据读取失败 - 多个私有库就写多个对象,顺序无关,但建议把最常用的那个放前面
auth.json 路径、权限、字段名错一个字就认证失败
Composer 不会告诉你哪错了,只返回 HTTP Basic: Access denied 或静默 404。
- Linux/macOS 下必须是:
~/.composer/auth.json(不是项目根目录下的auth.json);Windows 是:%APPDATA%\Composer\auth.json - 权限必须设为
600:chmod 600 ~/.composer/auth.json,否则直接忽略 - GitLab 必须用
http-basic字段,结构为:{"http-basic": {"gitlab.example.com": {"username": "oauth2", "password": "glpat-xxx"}}} - 域名 key(如
gitlab.example.com)必须和repositories.url中的 host 完全一致:不含协议、端口、路径;gitlab.example.com:8080和gitlab.example.com是两个不同 key
require 的包名必须和私有库 composer.json 的 name 字段完全一致
Composer 不按 Git 路径匹配,只严格比对私有库自身 composer.json 里的 name 字段。
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
- 假设私有库根目录
composer.json写的是{"name": "acme/utils"},主项目require就只能写"acme/utils": "dev-main" - 不能写成
"Acme/utils"(大小写错)、"acme-utils"(连字符错)、"utils"(缺 vendor 段)、或省略acme/段 - 分支版本必须加
dev-前缀:"dev-main"可行,"main"或"*"会被当成模糊匹配,找不到 - 远程分支或 tag 必须真实存在:
"dev-main"要求远程有main分支,"1.2.3"要求有对应 Git tag,不是v1.2.3或release-1.2.3
packagist.org 必须显式关闭,否则私有源永远不生效
即使 repositories 数组里第一个就是你的私有源,只要 packagist.org 没关,Composer 就永远先查官方源兜底。
-
{"packagist.org": false}必须是repositories数组里的一个**独立对象**,不能嵌套进其他仓库配置里 - 它必须放在私有源之后、数组末尾,例如:
"repositories": [ {"type":"vcs","url":"https://gitlab.example.com/acme/utils.git"}, {"packagist.org": false} ] - 写成
"packagist": false或"packagist.com": false会被静默忽略 - 别用
composer config --global repos.packagist false,这是全局污染,其他项目会崩
最容易被忽略的是:你改了 auth.json 或 composer.json,但没清缓存、没验证权限、也没确认 packagist.org 是否真关掉了——这几个点只要漏一个,就会回到“包不存在”的假象里。










