本地插件未被识别需同时满足：type为composer-plugin、extra.class指定正确类路径、autoload能解析该类；否则静默失效。
本地插件没被识别？先确认 type 和 extra.class 是否同时满足
Composer 只有在插件包的 composer.json 中同时满足三个硬性条件，才会尝试加载它："type": "composer-plugin"、"extra": {"class": "Your\Namespace\Plugin"}、且该类路径能被 autoload 正确解析。缺一不可——哪怕只漏掉 extra.class，插件就彻底静默失效。
常见错误是把插件当普通包写，比如 "type": "library" 或压根没设 type，此时 Composer 完全不会触发插件机制。
-
autoload必须覆盖入口类，例如"psr-4": {"Acme\Plugin\": "src/"}，对应类文件路径为src/Plugin.php -
extra.class的命名空间必须与autoload声明完全一致，大小写敏感 - 插件类必须
use ComposerPluginPluginInterface并实现activate()方法
composer require 本地插件失败？repositories 配置位置和格式不能错
项目根目录的 composer.json 必须在最外层声明 repositories 数组，类型为 path，URL 是相对于该 composer.json 的路径（如 "./my-composer-plugin"）。写在 require 里、写成绝对路径、或用 file:// 前缀，都会导致 Composer 跳过该仓库且不报错。
执行安装时，包名和版本必须与本地插件包内 composer.json 的 name 和 version（或分支名）严格一致。例如插件包里写的是 "name": "acme/my-plugin", "version": "dev-main"，那命令就得是 composer require acme/my-plugin:dev-main。
- 本地插件目录下必须存在合法的
composer.json，语法错误或缺失name字段会导致仓库被忽略 - 如果插件包没设
version，项目级composer.json需显式加"minimum-stability": "dev"，否则dev-main会被稳定性策略过滤 - 执行
composer require前，确保当前工作目录是项目根目录（即含composer.json的目录）
插件装上了但 activate() 没执行？检查接口实现和事件注册时机
插件类的 activate() 方法只在首次启用时调用一次，它本身不负责监听事件——你得在 activate() 内手动调用 $composer->getEventDispatcher()->addSubscriber() 来注册监听器。单纯实现 PluginInterface 不等于自动订阅任何事件。
典型错误是：写了 post-install-cmd 监听逻辑，却忘了在 activate() 里把它挂到事件分发器上；或者用了错误的接口（比如误实现了 EventSubscriberInterface 却没配对使用）。
- 监听
post-install-cmd或post-update-cmd时，事件对象是CommandEvent，可通过$event->getComposer()获取实例 - 不要在
activate()中直接操作$composer->getPackage()，此时拿到的可能是锁文件解析后的CompletePackage，而非原始配置 - 调试时可在
activate()开头加file_put_contents('/tmp/plugin-activated', 'yes');快速验证是否被调用
为什么 dump-autoload 对插件没用？插件加载不走 autoload 流程
composer dump-autoload 只刷新 PHP 类的自动加载映射，它对插件的激活、事件注册、命令注册等行为完全无效。插件是在 Composer 启动早期阶段通过插件 API 加载的，和 PSR-4 自动加载无关。
如果你改了插件类名、命名空间或 extra.class，必须先删掉 vendor/composer/autoload_plugins.php（或整个 vendor），再运行 composer install 或 composer update 才能重新触发插件发现流程。
- 修改插件代码后，仅
composer update acme/my-plugin不一定重载插件逻辑，因为 Composer 可能跳过已安装包的重新激活 - CI 环境中若缓存了
vendor，需确保清理autoload_plugins.php或禁用插件缓存 - 插件中的命令类（如
CustomCommand）需在activate()中通过$application->add(new CustomCommand())显式注册，否则composer my:command不会出现
