虚拟包是通过repositories声明type为package的条目,仅含name、version和provide字段,不提供文件也不安装,仅在依赖解析阶段模拟已满足供给;它不生成自动加载映射,需额外配置autoload或files才能避免Class not found。

Composer 本身不支持“虚拟包”作为真实可安装的依赖,但你可以用 package 类型的自定义仓库 + provide 字段,让 Composer 认为某个扩展已存在,从而跳过实际安装、绕过冲突或满足硬性依赖。这在测试、CI 环境或企业私有框架中很常见。
什么是虚拟包?它不是真包
所谓“虚拟包”,是通过 composer.json 的 repositories 声明一个 type 为 package 的条目,里面只写 name、version 和 provide,不提供 dist / source,也不含任何文件。Composer 解析依赖图时会把它当作已满足的“供给者”,但不会下载、解压或写入 vendor/。
- 它不能替代自动加载逻辑——
provide只影响依赖解析,不生成autoload.php映射 - 它无法解决 Class not found 错误,除非你已手动确保类可用(比如通过
filesautoload 或提前 require) - 它对
composer update有效,但对composer install(无composer.lock)可能被忽略,因为 lock 文件里没记录该包的实际“安装状态”
怎么声明一个虚拟包来模拟 yii2-debug
假设你正在构建一个不带调试工具栏的生产镜像,但某些包(如 yiisoft/yii2-gii)在 require 中硬依赖 yiisoft/yii2-debug,而你又不想真装它——这时可在根 composer.json 中添加:
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
{
"repositories": [
{
"type": "package",
"package": {
"name": "yiisoft/yii2-debug",
"version": "2.5.0",
"provide": {
"yiisoft/yii2-debug": "2.5.0"
}
}
}
],
"require": {
"yiisoft/yii2-gii": "^2.2"
}
}
-
version必须与依赖方要求的版本范围兼容(比如yiisoft/yii2-gii要求"yiisoft/yii2-debug": "~2.1.0",你就不能填"1.0.0") -
provide键名必须和依赖方require的包名完全一致,包括大小写和斜杠 - 别漏掉
repositories是数组,即使只加一个也要写成[{...}]
为什么 composer show 不显示这个虚拟包?
因为 composer show 默认只列出已安装到 vendor/ 的包,而虚拟包根本没落地。它只参与依赖解析阶段,一旦 Composer 完成图计算并写入 composer.lock,就不再追踪其“存在感”。验证是否生效,应看:
-
composer update --dry-run是否不再报yiisoft/yii2-debug未满足 -
composer why yiisoft/yii2-debug是否返回 “root package”(说明是 root 的 repositories 提供的) -
cat composer.lock | jq '.packages[] | select(.name == "yiisoft/yii2-debug")'—— 正常情况下这里应该为空
容易被忽略的坑:provide 不等于 autoload
最常踩的坑是以为加了 provide 就能直接 new DebugToolbar()。不行。虚拟包不生成任何 autoloader 条目,也不会把 yii2-debug 的 PSR-4 映射写进 vendor/composer/autoload_psr4.php。如果你需要类可用,还得额外做两件事:
- 在根
composer.json的autoload里手动加一条"yii\debug\": "path/to/mock-debug/src/"(指向你自己的空实现或桩类) - 或者用
"files": ["path/to/debug-stub.php"]提前载入关键类定义 - 否则运行时仍会抛
Class not found,和依赖解析成功与否无关

















