Composer虚拟包是通过provide字段声明“我提供某包能力”的逻辑占位符，不安装不加载；它必须配合repositories中配置的自定义仓库（如type: "package"）才能被识别和解析，否则Composer无法发现该虚拟包。
什么是Composer虚拟包，它和自定义仓库有什么关系
虚拟包（virtual package）不是真实存在的包，而是通过 provide 字段在 composer.json 中声明“我提供了某个包的能力”，让 Composer 认为该依赖已满足。它本身不下载、不安装、不生成 autoload 映射——只起逻辑占位作用。它必须配合自定义仓库（比如 type: "package" 或 type: "path"）才能被识别，否则 Composer 根本不会看到这个声明。
如何用 repositories + provide 实现可替换的抽象依赖
典型场景：你有一个接口 MyCompanyStorageDriverInterface，多个实现包（mycompany/s3-driver、mycompany/local-driver）都声明了 "provide": {"mycompany/storage-driver": "1.0"}。主项目只需 require 虚拟包 mycompany/storage-driver，再在 repositories 中显式列出其中一个实现，Composer 就能解析并安装对应实现。
关键实操点：
-
repositories必须写在项目根目录composer.json的根级数组里，不能嵌套在extra或其他字段中 - 每个
package类型仓库需完整描述：name、version、dist或source、provide，缺一不可 -
provide的包名必须和require的完全一致（包括大小写），否则匹配失败 - 若多个
package仓库都提供同一虚拟包，Composer 默认选第一个；想强制指定，得在require时加版本约束，如"mycompany/storage-driver": "dev-main as 1.0"
为什么 composer require 找不到虚拟包
这不是缓存或网络问题，而是以下任一条件未达成：
- 项目
composer.json没配置repositories，或者配置格式错误（例如漏了外层数组括号、type写成"packages"） - 虚拟包的
name和你在require里写的不一致，比如仓库里是"mycompany/cache-adapter"，你却写了require mycompany/cache_adapter -
package类型仓库没写version字段，且项目未设"minimum-stability": "dev"，导致dev-main这类分支名被过滤 - 你用了
path类型仓库但路径下没有合法composer.json（比如语法错误、缺name），Composer 会静默跳过该仓库，不报错也不提示
虚拟包 + 自定义仓库后 Class not found 怎么办
95% 的情况和虚拟包本身无关，而是自动加载链路断了：
- 确认提供虚拟包的那个实际实现包，其
composer.json里有正确的autoload配置（如"psr-4": {"MyCompany\S3\": "src/"}） - 运行
composer dump-autoload，否则新注册的命名空间不会写入vendor/autoload.php - 不要手动 require
vendor/autoload.php前就 new 类；也不要靠相对路径引入 autoload 文件 - 如果实现包含 bin 脚本或 ServiceProvider，这些仍需手动注册——
provide不触发任何脚本或自动发现逻辑
最常被忽略的一点：虚拟包不改变物理安装路径，所有类文件还是装在 vendor/ 下对应实现包的目录里；改了 vendor-dir 或用了 COMPOSER_VENDOR_DIR，就必须同步更新 require 路径和 IDE 配置，否则编辑器认不出类，运行时也找不到。
