yii2直传七牛云核心是服务端签发uploadtoken、客户端直传、key前缀模拟目录、回调验签落库；需配置crazyfd/yii2-qiniu扩展，指定区域，动态生成key，限制policy，启用https域名与回调验证。
Yii2 上传文件到七牛云，核心在于服务端生成安全凭证、客户端直传、路径可控、状态可追溯。不依赖中间服务器中转，既减轻带宽压力，又提升上传效率。
配置与安装：快速接入七牛 SDK
使用主流扩展 crazyfd/yii2-qiniu，它封装了官方 PHP-SDK，适配 Yii2 生命周期管理：
- 在
composer.json的require中添加："crazyfd/yii2-qiniu": "dev-master" - 执行
composer update安装后，确保vendor/crazyfd/yii2-qiniu目录存在 - 从七牛控制台获取 AK（AccessKey）、SK（SecretKey），创建 Bucket 并绑定自定义域名（如
https://img.example.com） - 注意 Bucket 所属区域（
east_china/south_china等），初始化时必须指定，否则上传会报up-z1.qiniup.com类错误
上传路径控制：按日期/业务分类自动建目录
七牛本身无传统“文件夹”概念，靠 key（文件唯一标识）的前缀模拟目录结构。推荐在服务端动态拼接：
- 例如生成
website/20260709/avatar_abc123.jpg，其中website/20260709/即逻辑目录 - PHP 代码示例：
$key = 'website/' . date('Ymd') . '/' . uniqid() . '.' . pathinfo($originalName, PATHINFO_EXTENSION); - 避免直接用用户原始文件名，防止路径遍历或特殊字符问题；建议统一用哈希或时间戳+随机串作为主键
安全上传：服务端签发 token，杜绝密钥泄露
前端绝不硬编码 AK/SK。正确做法是服务端生成一次性的上传凭证（uploadToken），并限定作用范围：
- 调用
Auth::uploadToken($bucket, $key, $expires=3600, $policy) -
$policy可限制最大文件大小、MIME 类型（如只允许image/*）、是否允许覆盖等 - 将 token 通过视图变量或 API 接口返回给前端，有效期建议设为 10–60 分钟，过期即失效
- 前端使用 Plupload 或原生 FormData + XMLHttpRequest，把 token 放入
multipart_params.token字段提交至七牛上传地址（如https://up-z2.qiniup.com）
上传后处理：链接生成、回调验证与元数据落库
上传成功后，需完成闭环操作：
- 调用
$qiniu->getLink($key)拼接出可访问 URL，注意域名是否启用 HTTPS、是否开启 CDN 缓存 - 启用七牛 上传回调（callbackUrl），服务端接收 JSON 回调，校验签名（
X-Qiniu-Callback-Signature），确认文件真实入库并更新数据库记录（如文件名、大小、类型、上传时间、业务关联 ID） - 若需图片处理（缩略、水印、裁剪），可在 URL 后追加样式名，如
https://img.example.com/photo.jpg?imageView2/1/w/200/h/200或绑定的自定义样式https://img.example.com/photo.jpg?watermark/1/image/xxx
