镜像源同步滞后导致元数据错位：阿里云、腾讯云等中文镜像常延迟10–30分钟，未同步更新dist.sha256或签名证书，使composer.lock中记录的哈希与实际下载包不一致，触发Signature verification failed；必须同步删除vendor和composer.lock并切回官方源重装，且allow-plugins需显式配置才生效。
插件签名校验失败，大概率不是插件本身问题，而是镜像源同步滞后或 allow-plugins 配置缺失。
为什么切中文镜像后出现 “Signature verification failed”
阿里云、腾讯云等镜像在同步新发布的 dist 包时，常存在 10–30 分钟延迟；更关键的是，它们未必同步更新 dist.sha256 字段或签名证书。而 Composer 安装时会严格比对 composer.lock 中记录的哈希值与实际下载包的哈希值——一旦不一致，就报 Signature verification failed 或 checksum verification failed。
这不是网络错误，也不是权限问题，是元数据错位。你本地 composer.lock 里存着 packagist.org 发布时生成的正确哈希，但镜像返回的是旧版包（或缓存响应），导致校验必然失败。
- 现象确认方式：临时切回官方源
composer config -g repo.packagist composer https://packagist.org，再运行composer install—— 若成功，基本可锁定为镜像问题 - 华为云镜像同步较稳，可作为国内备选；阿里云/腾讯云建议发布后等待至少 30 分钟再试
- CI 环境中若固定用镜像，建议加
sleep 60缓冲，或改用COMPOSER_NO_INTERACTION=1 composer install --no-cache减少缓存干扰
只删 vendor 不管用，必须连 composer.lock 一起清
composer clear-cache 只清本地 HTTP 缓存，不影响 composer.lock 里已写死的哈希值。只要 lock 文件没变，下次 install 仍会拿旧哈希去校验新下载的包——结果还是失败。
正确清理顺序是：
- 执行
rm -rf vendor composer.lock（Windows 用rd /s /q vendor & del composer.lock） - 确保当前用的是官方源：
composer config -g --unset repos.packagist && composer config -g repo.packagist composer https://packagist.org - 运行
composer install—— 此时会重新拉取完整元数据，生成带最新哈希的新composer.lock - 验证无误后，再决定是否换回镜像（不建议立即切回，尤其刚发版的插件）
allow-plugins 配置缺失导致插件“静默失效”
即使签名校验通过，插件也可能完全不执行——因为 Composer 2.2+ 默认禁用所有插件，allow-plugins 是硬性白名单，不是可选项。
常见错误表现：
- 插件类已安装，但
activate()方法从不被调用 - 命令未注册（如
php artisan xxx:command找不到） - 日志里无任何插件加载痕迹，也无报错
必须在项目根目录 composer.json 的顶层字段中显式声明：
{
"allow-plugins": {
"vendor/plugin-name": true
}
}
注意：
- 键名必须是完整 vendor/name，大小写敏感，不能用通配符（
"*"无效） - 若插件未发布到 Packagist，需先在
repositories中声明其来源，否则allow-plugins不会被识别 - 修改后需重新运行
composer install或composer update vendor/plugin-name生效
Composer 1 和 2 插件 API 不可能靠版本声明兼容
声明 "composer-plugin-api": "^1.0 || ^2.0" 在 Composer 2 下会直接拒绝安装，因为 v2 解析器不认识 v1 的事件类路径和方法签名；反过来，v1 也无法加载 v2 的 CommandProvider 接口。
所谓“兼容”，只能靠运行时探测实现：
- 在
activate()入口用class_exists('Composer\Script\Event')判断环境 - v1 路径走
EventDispatcher::addListener()，v2 路径走PluginManager::addCapability() - 所有对
Composer\Package\*等内部类的引用，都必须前置class_exists()检查 - 绝对不要在构造函数或静态块里 new v2 特有类，否则 v1 下直接 fatal error
最易被忽略的一点：composer.json 中 require 的 composer-plugin-api 版本必须唯一且明确——要么 "^1.1.0"（保老项目），要么 "^2.2.0"（用新特性），不能模糊。
