Yii2对接阿里云OSS需正确配置RAM子用户最小权限、地域匹配的Endpoint、SDK初始化异常处理及三种上传方式（临时文件/内存流/直传签名URL）。
在Yii2项目中对接阿里云OSS时，常因配置路径错位、权限策略缺失或SDK初始化时机不当，导致上传失败、文件403不可访问、或本地测试通而线上报签名错误。这些问题往往不报明确异常，只返回空响应或500内部错误，排查耗时远超集成本身。
创建RAM子用户并授权最小必要权限
登录阿里云控制台 → 搜索「RAM」→ 进入「用户管理」→ 点击「创建用户」→ 填写用户名（如 yii2-oss-prod），勾选「编程访问」→ 创建后立即复制 【AccessKey ID 和 AccessKey Secret】（仅显示一次，丢失需重新创建）。
进入该用户详情页 → 「添加权限」→ 搜索「AliyunOSSReadOnlyAccess」先测试读取；确认基础链路通后，再切换为自定义策略，避免直接授予 FullAccess 权限引发安全风险。
点击「新增授权策略」→ 选择「脚本编辑」→ 粘贴以下策略（将 your-bucket-name 替换为实际Bucket名）：
{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": ["oss:PutObject", "oss:GetObject", "oss:DeleteObject"], "Resource": ["acs:oss:*:*:your-bucket-name", "acs:oss:*:*:your-bucket-name/*"] } ] }
注意：不要遗漏 Resource 中的 【acs:oss:*:*:your-bucket-name/*】 后缀，否则 PutObject 会因权限不足静默失败。
配置Endpoint与Bucket地域强绑定
打开OSS控制台 → 进入目标Bucket → 左侧「概览」→ 「访问域名」→ 找到「外网Endpoint」，格式为 oss-cn-hangzhou.aliyuncs.com。
⚠️ 严禁使用形如 xiaxxxx-1486744522094157.oss-cn-beijing.oss-accesspoint.aliyuncs.com 的接入点地址——这是访问点（AccessPoint）格式，Yii2 SDK不识别，会导致连接超时或InvalidEndpoint错误。
确认你的Yii2应用部署地域与Bucket所在地域一致（例如ECS在华东2，Bucket也必须建在华东2），否则内网不通，强制走公网将产生额外流量费用且延迟升高。
在Yii2中注册OSS组件并注入配置
第一步：执行命令安装官方PHP SDK
composer require aliyuncs/oss-sdk-php
第二步：在 @app/components/AliyunOss.php 中定义组件类
注意：构造函数中不能直接 new OssClient，必须用 try/catch 包裹，否则配置错误时整个应用启动失败。
第三步：在 @app/config/params.php 中添加配置块
'oss' => [ 'accessKeyId' => 'LTAI5tQxxxxxxxxxxxxxx', 'accessKeySecret' => 'bZfxxxxxxxxxxxxxxxxxxxxx', 'bucket' => 'myapp-prod-assets', 'endpoint' => 'https://oss-cn-hangzhou.aliyuncs.com' ],
第四步：在 @app/config/main.php 的 components 数组中注册
'aliyunOss' => [ 'class' => 'app\components\AliyunOss', ],
上传逻辑中规避文件流与路径陷阱
方法一：上传临时文件（推荐用于表单上传）
接收 $_FILES['file'] 后，直接传入 move_uploaded_file() 生成绝对路径，再调用 $this->aliyunOss->upload($objectName, $absolutePath)；切勿传入 $_FILES['file']['tmp_name'] 路径字符串给SDK——OSS SDK会尝试 fopen 该路径，但部分Linux环境 tmp 目录权限受限，导致 Permission denied。
方法二：上传内存流（适用于裁剪后图像、动态生成PDF）
使用 php://memory 流：$stream = fopen('php://memory', 'r+'); fwrite($stream, $content); rewind($stream); 然后调用 $ossClient->putObject($bucket, $object, $stream)；务必在 upload 完成后 fclose($stream)，否则可能触发资源泄漏警告。
方法三：直传签名URL（适用于大文件或前端直传）
后端调用 $ossClient->signUrl($bucket, $object, 3600) 生成临时可写URL，返回给前端；前端用 XMLHttpRequest PUT 方式上传，无需经过Yii2应用服务器中转。此方式要求 Bucket ACL 必须为私有，且 RAM 用户策略中已包含 PutObject 权限。
