Composer 没有虚拟包概念,psr/* 等是真实发布的纯接口包;需发含 src 和 PSR-4 自动加载的真实包到 Packagist,不可用 provide 声明虚拟接口,否则运行时报 Class not found。

Composer 虚拟包不能声明接口规范
Composer 本身没有“虚拟包”这个概念。你看到的 psr/cache、psr/log 这类包,是真实存在的 Composer 包,由 PHP-FIG 维护并发布在 Packagist 上,只是它们只含接口定义、不含实现——不是“虚拟”,而是“纯契约”。所谓“虚拟包”常是误传,实际指代的是这些无实现的接口元包。
psr/* 包为什么能被 require 成功
它们依赖 Composer 的元包映射机制,不是靠 composer.json 中 provide 或 replace 声明出来的。关键点如下:
-
psr/cache等包在 Packagist 上有真实仓库,源码托管在 github.com/php-fig/cache,发布正式版本(如3.0.0) - 必须显式指定版本约束:
composer require psr/cache:^3.0;写composer require psr/cache会失败,因为该包无默认分支 - 安装后,
vendor/psr/cache/src/CacheInterface.php是真实文件,自动加载靠autoload.psr-4映射:"PsrCache\" => "src/" - 它不提供任何功能,只约定方法签名;你要用缓存,还得装
symfony/cache或laravel/framework这类实现包
想自己定义接口规范包?别用 provide,要发真实包
如果你希望团队共用一套接口(比如 acme/payment-gateway),正确做法是:
- 新建 Git 仓库,含标准
composer.json,name字段设为acme/payment-gateway - 在
src/下放接口类,如PaymentGatewayInterface.php,命名空间匹配AcmePaymentGateway - 配置
"autoload": {"psr-4": {"Acme\PaymentGateway\": "src/"}} - 打 tag(如
v1.0.0)并推送到 GitHub/GitLab,再在 Packagist 上 submit - 其他项目
composer require acme/payment-gateway:^1.0即可引入接口契约
不要试图用 "provide": {"acme/payment-gateway": "1.0"} 声明虚拟接口——这只会让依赖解析器“假装”已满足,但不会把接口类放进 vendor,也不会注册自动加载,运行时必报 Class not found。
provide 和 replace 的真实用途
这两个字段用于包替换场景,和接口规范无关:
-
provide:声明“我实现了某接口规范”,供其他包做conflict或require判断。例如monolog/monolog声明"provide": {"psr/log-implementation": "1.0.0"},表示它提供了PsrLogLoggerInterface的实现 -
replace:声明“我替代某个旧包”,常用于包重命名迁移,如guzzlehttp/guzzle替换掉旧的guzzle/guzzle - 二者都不生成或分发任何 PHP 类文件;它们只影响依赖图解析,不解决自动加载问题
真正要让接口可用,唯一可靠路径是:发一个带 src/ 和正确 autoload 的真实包,并确保它被 Packagist 索引。


















