什么是Composer的Metapackage？如何使用它管理复杂依赖？

Metapackage 是一个不包含源代码、仅声明依赖的空包，用于打包和复用一组固定版本的依赖组合；它无类无功能，仅在安装阶段生效，autoload 为空，type 推荐设为 “metapackage”。

Metapackage 是什么，它和普通 package 有什么区别？

composer 的 metapackage 本身不包含任何源代码，只是一个空的 composer.json 文件，只用来声明一组依赖。它的作用是「打包依赖关系」，不是提供功能。当你运行 composer require vendor/metapackage，实际安装的是它 require 字段里列出的所有包，而这个 metapackage 自身不会被加载——它的 autoload 通常为空或被显式禁用（"autoload": {"psr-4": {}})）。

常见误判是把它当成“工具集”或“SDK”，但其实它更像一个「依赖清单快照」：比如 laravel/framework 不是 metapackage，而 laravel/laravel（官方项目骨架）才是——它不提供类，只确保你装上 illuminate/*、symfony/* 等一整套组合。

如何创建一个最小可用的 metapackage？

关键点在于：不写源码、不注册自动加载、不发布逻辑类。只需一个合规的 composer.json，并打上 "type": "metapackage" 标签（非强制但强烈建议，可被工具识别）。

• name 必须符合 vendor/name 格式，且全局唯一
• require 列出你要聚合的包及其版本约束（如 "php": "^8.1", "monolog/monolog": "^3.0", "guzzlehttp/guzzle": "^7.5"）
• autoload 应设为空对象或完全省略（避免 Composer 尝试生成 autoload classmap）
• 不要放 src/、tests/ 目录，也不需要 index.php

{     "name": "acme/full-stack-tools",     "type": "metapackage",     "description": "All dev tools we use across projects",     "require": {         "php": "^8.1",         "phpunit/phpunit": "^10.0",         "friendsofphp/php-cs-fixer": "^3.14",         "vimeo/psalm": "^5.10"     },     "autoload": {} }

为什么 install 后看不到它的类，也调不到它的方法？

因为它根本没类。Metapackage 的价值在安装阶段，不在运行时。你执行 composer require acme/full-stack-tools 后，phpunit、php-cs-fixer 等会被装进 vendor/，但 acme/full-stack-tools 这个目录下只有 composer.json 和可能的 LICENSE ——没有 src/，也没有命名空间可引用。

常见踩坑：

• 试图 use AcmeFullStackToolsSomething; → 报错 Class not found（根本不存在）
• 在 autoload 里配了 PSR-4 → Composer 会尝试扫描空目录，浪费时间甚至报 warning
• 给 metapackage 设了 minimum-stability: dev → 它会污染整个项目的稳定性策略，导致其他依赖意外升级到 dev 版本

什么时候该用 metapackage，而不是直接写在根项目 composer.json 里？

适用场景很具体：当多个项目需要**完全一致的工具链或框架组合**，且你希望把这份依赖声明从每个项目中抽离出来统一维护。

例如：

• 公司内部所有 Laravel 项目都必须用同一组 PHP-CS-Fixer 规则 + Psalm 配置 + Pest 测试器 → 做一个 company/laravel-dev-kit
• CI 流水线中每次都要装相同扩展（ext-redis, ext-mbstring）和 CLI 工具 → 用 metapackage 封装成 company/ci-prerequisites，再让 CI 脚本 composer global require 它

反例：只为图省事把几个常用包塞进一个 metapackage，却不打算复用或版本对齐——这种做法反而增加维护负担，还模糊了依赖来源。

真正难处理的是版本冲突：如果两个 metapackage 分别要求 guzzlehttp/guzzle:^6 和 ^7，Composer 会直接拒绝安装。这种耦合必须在设计 metapackage 时就对齐约束，不能等到集成时才发现。