Composer自定义命令需通过type:composer-plugin包实现，主类实现CommandProviderInterface::getCommands()返回BaseCommand实例，并在composer.json中声明插件类型及兼容API版本。
很多开发者可能都想过：能不能给Composer加个自己的命令？答案是可以，但路径和你想的或许不太一样。Composer本身并不直接支持那种“扔个脚本到bin目录”就能用的命令行扩展。所谓的“自定义命令插件”，本质上是通过创建一个composer-plugin类型的包，并实现CommandProviderInterface接口来完成的——关键在于让Composer识别并加载你的插件。
怎么让Composer认出你的自定义命令
问题的核心不在于命令怎么写，而在于插件如何被声明和发现。Composer只会从已安装的、且类型为composer-plugin的包中，去寻找那些实现了Composer\Plugin\CommandProviderInterface的类。
- 首先，在你的插件包
composer.json里，必须明确声明"type": "composer-plugin"。 - 其次，
require字段里需要包含"composer-plugin-api": "^2.0"（对应Composer 2.x）或"^1.0"（对应Composer 1.x），这确保了API兼容性。 - 然后，你的主类需要实现
Composer\Plugin\CommandProviderInterface::getCommands()方法，这个方法要返回一个Command实例的数组。 - 最后，确保这个类在
autoload配置下能够被自动加载，推荐使用"psr-4"规范。
为什么你的命令没出现在composer list里
命令写好了，插件包也建了，但运行composer list却看不到？最常见的原因是插件没有被激活。Composer不会自动加载你本地正在开发的插件，它必须被正式安装。
- 要么通过
composer global require全局安装， - 要么通过
composer require --dev安装到目标项目中。
并且，这个插件包需要是已发布的，或者通过repositories配置指向了有效的本地路径。排查时，可以：
- 用
composer global show确认插件是否已全局安装。 - 用
composer show --plugin（Composer 2.2+支持）查看当前项目启用的插件列表。 - 注意，如果插件类的构造函数抛出异常，Composer会静默跳过它，既不报错也不会注册命令。
- 务必检查
getCommands()返回的是Composer\Command\BaseCommand子类的实例，而不是类名字符串或其他未实例化的对象。
Command类怎么写才真正可用
这里有个关键细节：你的命令类不能直接继承Symfony\Component\Console\Command\Command。必须继承Composer\Command\BaseCommand，否则你将无法在命令内部通过$this->getComposer()和$this->getIO()来获取Composer实例和输入输出对象。
- 重写
configure()方法，用setName("myplugin:do-something")来设置命令名，这个名字最终会出现在composer list里。 - 在
execute()方法中，你可以通过$this->getComposer()->getPackage()来获取当前项目的信息。 - 处理输入参数时，建议使用
$input->getOption("force")这样的方式，而不是直接操作$_SERVER，这能保证与Composer原生命令行为的一致性。 - 需要警惕的是，尽量避免在
execute()里调用exec()或shell_exec()去执行另一个composer install命令，这可能会引发嵌套加载、锁文件冲突等难以调试的问题。
protected function configure(): void
{
$this->setName('myplugin:dump-config')
->setDescription('Dump current composer config as JSON');
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$io = $this->getIO();
$composer = $this->getComposer();
$config = $composer->getConfig()->all();
$io->write(json_encode($config, JSON_PRETTY_PRINT));
return 0;
}
调试时最容易忽略的加载时机问题
这是插件开发中的一个“坑点”：Composer插件在Composer\Autoload\ClassLoader初始化之前就已经尝试加载了。这意味着，你不能依赖vendor/autoload.php中那些尚未注册的第三方库——即使你已经在插件包的require里声明了它们。
- 因此，插件类自身应该尽量保持轻量，避免在构造函数中执行繁重的操作。
- 所有外部依赖（比如Guzzle、Symfony Console组件等）都必须明确声明在插件包的
require中，并且要注意版本兼容性。例如，如果你的插件引用了Symfony 6的组件，但它可能与Composer 2.2内置的旧版Console组件不兼容。 - 另外，如果你使用
repositories配置将路径指向本地插件进行开发，记得每次修改代码后，运行composer update myvendor/myplugin来更新。否则，Composer的缓存可能会让你误以为修改没有生效。
