私有 Composer 插件必须在 composer.json 中显式声明 "type": "composer-plugin" 且含有效 "extra.class"；需打语义化版本标签；PHP 与 composer-plugin-api 版本须兼容；repositories 需正确配置 type: "vcs" 和合法 Git URL。
私有仓库插件的 composer.json 必须显式声明 type: "composer-plugin"
Composer 不会自动识别一个包是插件，哪怕它实现了 PluginInterface。如果 composer.json 里没写 "type": "composer-plugin"，composer require 装完也不会激活——你监听的 pre-install-cmd 或 post-autoload-dump 事件根本不会触发。
常见错误现象：插件代码已拉取、类文件存在、composer dump-autoload 也成功，但事件监听完全静默。
- 检查点：打开私有仓库根目录下的
composer.json，确认顶层有且仅有一个"type": "composer-plugin" - 额外要求：
extra.class字段必须存在且指向可 autoload 的完整类名（如"YourVendor\MyPlugin"），路径需与autoload配置匹配 - 别用
"type": "library"或留空——这会让 Composer 当普通依赖处理，跳过插件注册流程
私有仓库必须提供语义化版本标签，不能只靠 dev-main
Composer 插件在安装或更新时，会按版本约束去解析依赖图；如果你的私有插件只维护 dev-main 分支，没有打 v1.0.0 这类 tag，composer update 就可能反复报错 Could not find a matching version，尤其当项目 composer.json 写了 "your-vendor/my-plugin": "^1.0" 时。
原因在于：Composer 默认忽略 dev- 前缀分支，除非你显式指定 "require" 中用 "dev-main as 1.0.0" 这种 alias 写法，但这不可靠，CI/CD 环境下容易出错。
- 实操建议：每次功能合入 main 后，立即执行
git tag v1.2.3 && git push origin v1.2.3 - 标签命名必须符合 Semver：主版本变更要重估兼容性，比如从
v1.x升到v2.0，若插件修改了事件监听签名（如把Event $event改成PackageEvent $event），下游项目就可能运行时报ArgumentCountError - 验证方式：在测试项目中运行
composer show your-vendor/my-plugin --all，能看到列出的 tag 才算生效
私有仓库插件的依赖必须与目标项目 PHP 版本和 Composer API 兼容
插件本身也是 PHP 包，它的 composer.json 里写的 "php" 和 "composer-plugin-api" 约束，会参与整个项目的依赖解析。如果私有插件要求 "php": "^8.2"，但你的 Laravel 9 项目还在跑 PHP 8.1，composer require 就会直接失败，提示 Your requirements could not be resolved，而不是等装完再报错。
更隐蔽的问题是 composer-plugin-api 版本错配：Composer 2.x 对应 ^2.0，而旧插件若还锁着 "composer-plugin-api": "^1.1"，在 Composer 2.9.6 下会加载失败，日志里出现 Class "Composer\Plugin\PluginInterface" not found。
- 检查项：私有插件的
composer.json中必须含"composer-plugin-api": "^2.0"（对应 Composer 2.x）或"^3.0"（若已适配 Composer 3 beta） - PHP 版本约束建议写宽一点，比如
"php": "^7.4 || ^8.0 || ^8.1 || ^8.2"，避免因 CI 环境 PHP 小版本差异中断构建 - 不要在插件里 require
composer/composer—— 它是运行时注入的，硬依赖会导致循环引用和 autoload 冲突
repositories 配置漏掉 type: "vcs" 或 URL 格式非法导致插件无法发现
私有 Git 仓库插件不托管在 Packagist，就必须在使用方项目的 composer.json 顶层 repositories 数组里声明。但很多人只写了 URL，忘了设 "type": "vcs"，结果 composer require your-vendor/my-plugin 依然报 Could not find package。
另一个高频坑是 URL 写成 GitHub 页面地址（https://github.com/xxx/yyy）而非 Git 协议地址（https://github.com/xxx/yyy.git）。Composer 的 vcs 类型解析器会拒绝前者，错误信息很模糊：Invalid repository type 或直接跳过该源。
- 正确写法示例（HTTPS）：
{"type": "vcs", "url": "https://github.com/your-org/my-plugin.git"} - SSH 地址需确保 SSH key 已配置且能
git clone git@github.com:your-org/my-plugin.git成功，否则卡在Cloning failed - 多个私有仓库别堆在同一个项目里——每多一个
vcs源，composer update就得多一次元数据探测，拖慢 2~5 秒，且易触发 rate limit
真正容易被忽略的是插件事件监听的执行时机：它只在 composer install 或 update 的生命周期内触发，不会在 composer dump-autoload 单独运行时激活。如果你以为改了 autoload 就能重载插件逻辑，实际得删掉 vendor 和 composer.lock 重新装一遍。
