Composer元包（metapackage）是仅声明依赖、不包含源代码和autoload配置的空包，type必须设为"metapackage"以被正确识别，否则将被误作普通包处理并引发autoload错误或兼容性问题。
Composer 元包（metapackage）不是“功能包”，它不提供任何类、不执行任何逻辑，只在 composer install 或 composer require 阶段触发依赖安装——你装的是它 require 里的那些包，而不是它自己。
为什么 type 必须设为 "metapackage"
这是 Composer 识别元包的唯一依据。如果漏写或写成 "library"，Composer 会把它当普通包处理：尝试生成 autoload、检查 src/ 目录、甚至报错 “Class not found”。更隐蔽的问题是，某些工具（如 composer-unused 或 IDE 插件）会因类型不符跳过分析或误判依赖。
-
type字段必须显式声明为"metapackage"，不能省略 - 不要同时配置
autoload字段——哪怕写成{"psr-4": {}}也不行，否则 Composer 会尝试加载空映射，引发警告或兼容性问题 - Packagist 不校验
type是否合规，但下游项目若用 Composer 2.5+，会严格按类型决定是否跳过 autoload 生成
composer.json 里哪些字段能写、哪些绝对不能碰
元包的 composer.json 极简，但每项都有明确语义。写错一个字段，轻则别人 require 失败，重则被 Packagist 拒绝索引。
-
name必须是小写vendor/name格式（如acme/dev-tools），且vendor部分需与你在 Packagist 的用户名一致 -
require是唯一核心字段：列出你要聚合的包，例如"phpunit/phpunit": "^9.6"、"friendsofphp/php-cs-fixer": "^3.14" -
autoload字段必须完全删除——不是设为空对象，是彻底不出现。存在即错误 -
description和license推荐填写，前者影响 Packagist 页面可读性，后者是索引硬要求（空值会导致提交失败）
本地测试时为什么 composer require 报错 “Could not find a matching version”
这不是元包本身的问题，而是 Composer 在解析依赖时卡在了路径或版本约束上。常见于开发阶段未正确配置本地仓库。
- 确保目标项目
composer.json的repositories中添加了path类型源，例如：{"type": "path", "url": "../acme-dev-tools"} - 路径必须是相对项目根目录的，且不能含空格或中文；
../acme-dev-tools下必须有合法composer.json，且含name字段 - 元包自身不需要打 Git tag 就能本地测试，但若你手动加了
"version": "dev-main"，请删掉——Composer 完全忽略该字段，反而可能干扰解析 - 运行
composer require acme/dev-tools --no-update再composer update acme/dev-tools，可绕过早期版本冲突判断
发布到 Packagist 后别人 require 不到稳定版？
元包没有“代码”，但它依然依赖 Git tag 才能被 Packagist 视为有效版本。没有 tag，就只有 dev-main，而默认 minimum-stability 是 stable，所以用户 require 时根本看不到可用版本。
- 必须打带
v前缀的语义化标签，例如：git tag v1.0.0，然后git push origin v1.0.0 - 不要用
git push --tags，它可能推送大量无效历史 tag，污染 Packagist 版本列表 - Packagist 默认每 15 分钟轮询一次，首次提交后建议手动点 “Update” 强制抓取
- 标签内容无需特殊处理：只要
composer.json合规，tag 指向的 commit 里有它就行，不用额外改代码
最容易被忽略的一点：元包不参与自动加载，也不应出现在 vendor/autoload.php 的 classmap 里——如果你发现某个工具命令（比如 php-cs-fixer）没出现在 vendor/bin/，不是元包没生效，而是它依赖的包本身没正确注册 bin。检查那个包的 bin 字段是否声明了可执行文件。
