加 -v 参数可显示完整错误信息，包括HTTP错误、版本冲突、网络超时等；需检查fxp插件兼容性、composer.lock版本、缓存及脚本执行情况。
扩展包安装报错时，Composer 默认只显示模糊提示（比如 The package is not available in a stable-enough version），根本看不出是网络、权限、版本约束还是插件问题——必须主动触发详细错误输出才能定位。
运行 composer install 或 composer require 时加 -v 参数
这是最直接有效的手段。不加参数时 Composer 会折叠关键信息；加 -v（verbose）后，它会打印完整请求链、匹配的包版本、依赖冲突树和实际失败原因：
- 常见输出如：
[Composer\Downloader\TransportException] The "https://api.github.com/repos/yiisoft/yii2/zipball/..." file could not be downloaded (HTTP/2 401)→ 表明 GitHub Token 权限不足 - 或：
Root composer.json requires yiisoft/yii2-bootstrap4 ^2.2, found yiisoft/yii2-bootstrap4[dev-master, 2.3.x-dev] but these do not match...→ 版本约束与可用分支不兼容 - 若卡在
Loading composer repositories with package information超过 30 秒 → 基本是国内网络无法连通 packagist.org 或 GitHub
检查 fxp/composer-asset-plugin 是否失效
Yii2 扩展常依赖 bower/npm 资源，而 fxp/composer-asset-plugin 是旧版处理这类资源的核心插件。PHP 8.5+ 或 Composer 2.5.8 后该插件已不可用，但错误仍表现为“找不到包”：
- 执行
composer global show fxp/composer-asset-plugin，若无输出或版本低于1.4.6，说明插件未安装或过期 - 不要运行
composer global require fxp/composer-asset-plugin:dev-master—— 这在新环境中会直接报错 - 正确做法：删掉插件（
composer global remove fxp/composer-asset-plugin），改用yidas/yii2-composer-bower-skip替代，且必须配合"fxp-asset": {"enabled": false}配置项
查看 composer.lock 和 vendor/composer/installed.json
很多“安装成功但运行时报 Class not found”的问题，根源是 Composer 实际没装进预期版本，而是 fallback 到了兼容版或空包：
- 打开
composer.lock，搜索你要装的扩展名（如"name": "kartik-v/yii2-widget-datepicker"），确认version字段是否为你指定的版本，且source的url可访问 - 若
vendor/composer/installed.json里完全找不到该扩展条目 → 说明require没生效，可能是minimum-stability设置过高（如设为stable却试图装dev-master） - 此时应临时降级：在
composer.json里加"minimum-stability": "dev"和"prefer-stable": true并重试
强制刷新本地缓存并禁用脚本
Composer 缓存损坏或 pre-install-scripts 执行失败，会导致静默跳过关键步骤，看起来像“没报错但没装上”：
- 先清缓存：
composer clear-cache（不是dump-autoload） - 再重装时加
--no-scripts --no-plugins参数，绕过所有钩子，验证是否是某脚本中断导致 - 如果此时能成功写入
vendor/，说明问题出在某个扩展的post-install-cmd（比如 asset 发布失败） - 最后单独执行：
composer run-script post-install-cmd，看哪一行崩了
真正难排查的从来不是报错本身，而是 Composer 把错误吞掉之后还假装成功——所以每次 require 或 update 后，别急着跑应用，先翻 vendor/ 目录有没有对应文件夹，再查 composer.lock 里的版本号，比盯着空白终端猜强得多。
