必须用composer require安装，不可手动解压ZIP、修改vendor或复制autoload配置；查扩展兼容性应以composer.json中"require"字段的yiisoft/yii2版本声明为准，而非README描述。
直接用 composer require 装，别手动解压 ZIP、别改 vendor 目录、别抄 autoload 配置——90% 的扩展失败都卡在这一步。
怎么查一个扩展是否支持当前 Yii 版本
看包的 composer.json 里 "require": {"yiisoft/yii2": ">=2.0.14"} 这类声明，不是看 GitHub README 里写的“兼容 Yii2”。很多包 README 没更新，但 composer install 会硬校验。比如 johnlui/aliyun-oss 明确要求 aliyun/oss-sdk-php v2.4.x，装 v3.x 就会报 Class 'Aliyun\OSS\OssClient' not found，因为命名空间变了。
- 执行
composer show yiisoft/yii2确认你本地 Yii 主版本（如2.0.45） - 去 packagist.org 搜扩展名，点开后看 “Requires” 栏里的
yiisoft/yii2版本范围 - 如果扩展没维护了（最后更新是 2021 年前），优先找替代方案，比如用原生 SDK + 自封装 Component
装完扩展为什么 Class Not Found
常见原因不是没装上，而是 autoloader 没生效或类路径写错。Composer 安装后不会自动刷新 autoload，尤其在开发环境改过 composer.json 又删过 vendor 时。
- 先跑
composer dump-autoload -o强制重生成优化版 autoload - 检查
use语句：比如yii\sphinx\Query不是yii2sphinx\Query，大小写和命名空间必须完全匹配 - 确认扩展没被
autoload-dev包围——有些包把主类放进了dev分支，正式安装时不会载入 -
vendor/autoload.php必须被入口脚本（如web/index.php）引入，漏掉这行就全白搭
配置扩展时 endpoint、bucket、key 容易写错哪
阿里云 OSS 类扩展最常翻车的地方不在代码，而在配置字符串本身。这些值不报语法错，但一运行就超时或 403。
-
endpoint必须带协议且不能含 bucket：写成https://oss-cn-hangzhou.aliyuncs.com✅，写成oss-cn-hangzhou.aliyuncs.com❌（缺 https://），写成https://my-bucket.oss-cn-hangzhou.aliyuncs.com❌（多了 bucket） -
bucket名只允许小写字母、数字、短横线，不能有下划线或大写，否则抛InvalidBucketName -
accessKeyId和accessKeySecret别硬编码在 config 里，应从params-local.php或环境变量读取，避免提交到 Git - 内网 endpoint（如
oss-cn-hangzhou-internal.aliyuncs.com）只在阿里云 ECS 同地域可用，本地开发直接连不上，也不会立刻报错，而是卡住几秒后 timeout
扩展不是黑盒，它只是把 SDK 封装成 Yii Component，没做连接池、没加重试、没校验配置合法性。真出问题，得顺着 vendor 里实际调用的 SDK 方法往里跟——比如 johnlui/aliyun-oss 底层就是调 aliyun/oss-sdk-php 的 OssClient，日志和异常源头都在那儿。
