直接执行 composer require "johnlui/aliyun-oss" 安装，该扩展是 Yii2 适配版，依赖 aliyun/oss-sdk-php（建议 v2.4.x），需正确配置 accessKeyId、accessKeySecret、带协议的 endpoint（如 https://www.php.cn/link/116c87e094144d0002cff857e56a322f）和 bucket，注意权限、网络及 PHP 环境要求。
怎么装 yii2-aliyunoss 扩展
直接用 Composer 装，别手动下载 ZIP 或改 vendor。这个包维护还行，但只支持阿里云 OSS 的基础上传/下载/删除，不带 STS 临时凭证或分片上传封装。
执行命令：composer require "johnlui/aliyun-oss"（注意不是官方 SDK，是社区封装的 Yii2 适配版）
johnlui/aliyun-oss 依赖 aliyun/oss-sdk-php，Composer 会自动拉取兼容版本（建议用 v2.4.x，v3.x 有 breaking change）
常见错误现象：Class 'Aliyun\OSS\OssClient' not found —— 多半是 aliyun/oss-sdk-php 没装上，或者 autoloader 没刷新，运行 composer dump-autoload 再试
别把扩展当成“开箱即用”的组件：它只是把 SDK 封装成 Yii2 的 Component，没做配置校验、连接池、重试策略这些
配置里怎么写 accessKeyId 和 endpoint
阿里云 OSS 的 endpoint 必须带协议（https://），且不能带 bucket 名。比如杭州区域要写 <a href="https://www.php.cn/link/116c87e094144d0002cff857e56a322f">https://www.php.cn/link/116c87e094144d0002cff857e56a322f</a>，而不是 <a href="https://www.php.cn/link/f86e80e20c504f532b6664fcb25c7dbb">https://www.php.cn/link/f86e80e20c504f532b6664fcb25c7dbb</a>
在 main.php 或 params-local.php 中配好敏感信息，再注入到组件：
'components' => [
'oss' => [
'class' => 'johnlui\AliyunOSS\AliyunOSS',
'accessKeyId' => '<code>your-access-key-id</code>',
'accessKeySecret' => '<code>your-access-key-secret</code>',
'endpoint' => '<code>https://www.php.cn/link/116c87e094144d0002cff857e56a322f</code>',
'bucket' => '<code>my-bucket</code>',
],
],
容易踩的坑：
-
accessKeyId和accessKeySecret写错位置（比如混进params却没在组件里引用） -
endpoint写成内网地址（如oss-cn-hangzhou-internal.aliyuncs.com），但你的应用不在阿里云 ECS 上，结果连不上又没报错，超时卡死 -
bucket名含大写字母或下划线 —— OSS 不允许，会直接抛InvalidBucketName异常
上传文件时路径怎么处理才不会覆盖或 404
OSS 没目录概念，key 就是完整路径字符串。你传 uploads/avatar/123.jpg，它就存成那个 key；传 /uploads/...（开头带斜杠），OSS 也会照单全收，但部分 SDK 会自动 trim，行为不一致
实操建议：
- 统一用相对路径（不以 / 开头），比如 uploads/2024/06/abc.jpg
- 文件名建议用 UUID 或时间戳 + 原扩展名，避免中文名或空格（URL 编码易出错，CDN 回源也可能失败）
- 上传前先调 $oss->exists($key) 判断是否已存在，需要防重就加逻辑，不需要就跳过（OSS 默认覆盖）
示例：
$key = 'uploads/' . date('Y/m') . '/' . uniqid() . '.' . $extension;
$result = Yii::$app->oss->uploadFile($localPath, $key);
if (!$result) {
throw new Exception('OSS upload failed');
}
注意：uploadFile() 返回布尔值，不是 SDK 原生的 OssResult 对象，没法直接取 ETag 或版本 ID；如果需要元数据，得自己调 $oss->getOssClient()->putObject(...)
为什么本地能跑线上 403 或 timeout
403 最常见原因是 RAM 子账号权限不足。主账号 AK 能过，子账号 AK 往往只给了 AliyunOSSFullAccess，但没显式授权对应 bucket 的 oss:GetObject 等动作。去 RAM 控制台检查策略 JSON，确认包含：
{
"Effect": "Allow",
"Action": ["oss:GetObject", "oss:PutObject", "oss:DeleteObject"],
"Resource": ["acs:oss:*:*:my-bucket", "acs:oss:*:*:my-bucket/*"]
}
timeout 多半是 endpoint 写错，或服务器所在网络无法直连公网 OSS（比如某些 IDC 或海外节点）。可以 SSH 进机器，用 curl -v <a href="https://www.php.cn/link/116c87e094144d0002cff857e56a322f">https://www.php.cn/link/116c87e094144d0002cff857e56a322f</a> 测试连通性
另一个隐藏坑：php.ini 里 allow_url_fopen=Off 会导致 SDK 底层 cURL 初始化失败，报错不明显，建议统一开；同时确认 openssl 扩展已启用，否则 HTTPS 请求会直接挂
OSS 的错误信息藏得深，uploadFile() 失败只返回 false，真要 debug 得捕获 try/catch 里的 Exception，或者临时改源码加日志——这点很多人忽略，查半天以为是网络问题，其实是权限或证书问题
