Metapackage 是 Composer 中不包含实际代码、仅通过 require 字段声明依赖的特殊包，用于批量安装和统一管理版本；需设 "type": "metapackage" 且不可含 autoload。
Metapackage 是 Composer 中一种不包含实际代码的特殊包，它的作用是声明一组依赖，用于批量安装或统一管理其他包的版本约束。
Metapackage 的核心特点
它本身没有源码文件（src/、lib/ 等目录），只有 composer.json；不提供功能，只通过 "require" 字段“组合”其他包；常被用作“发行版入口”，比如 Laravel、Symfony 官方提供的安装器包就是 metapackage。
如何创建一个 metapackage
只需新建一个空目录，放入最小化的 composer.json：
Comprehensive Three.js 3D graphics reference
下载
详细的 Three.js 3D 图形参考，涵盖场景设置、相机、几何体、材质、光照、动画、控制器、加载器、数学工具和调试。
{
"name": "your-vendor/app-stack",
"description": "A stack of packages for my projects",
"type": "metapackage",
"require": {
"monolog/monolog": "^2.10",
"guzzlehttp/guzzle": "^7.8",
"symfony/console": "^6.4"
}
}
-
必须设置
"type": "metapackage"—— 这是关键标识，让 Composer 知道它不需 autoload，也不应被当作可加载库处理 - 不要写
"autoload"字段 —— metapackage 不提供类或函数 - 发布到 Packagist 或私有仓库后，别人就能像普通包一样 require 它
如何使用 metapackage
在目标项目的 composer.json 中添加它为依赖即可：
"require": {
"your-vendor/app-stack": "^1.0"
}
运行 composer install 后，Composer 会自动拉取它声明的所有依赖（如 monolog、guzzle、symfony/console），并按指定版本安装。
- 它不会覆盖项目中已存在的同名包版本，除非冲突 —— Composer 仍遵循整体依赖解析规则
- 适合团队统一技术栈：定义一套“标准组件集”，新项目只需 require 一个包，避免重复写一堆 require
- 升级时只需更新 metapackage 版本，所有子包版本随之批量升级（前提是 metapackage 自身更新了 require 约束）
注意事项和常见误区
- metapackage 不能替代
composer create-project—— 后者用于初始化全新项目结构，前者只是依赖聚合 - 不要给 metapackage 加版本别名（如
"dev-main as 1.0"）来绕过稳定性检查，容易引发不可控依赖行为 - 如果某个子包需要自定义配置（如 Laravel 的 service provider 注册），metapackage 不会自动处理 —— 那些仍需手动配置
- 调试依赖问题时，注意区分：错误来自 metapackage 声明的约束，还是子包自身逻辑
