yii\imagine\Image 是 Yii 2 官方推荐的图片处理方案，自动适配 GD/Imagick 驱动，支持 thumbnail（含 INSET/OUTBOUND 模式）、crop、watermark、text 等操作，无需手动配置组件，装完即用。
yii\imagine\Image 是 Yii 2 中处理图片最常用、也最可靠的方案，它不依赖旧版 CImageComponent（那是 Yii 1 的东西），也不需要手动注册组件——装完就能用。
你不需要配置 components 里的 image，更别去改 main.php 加 GD 驱动声明。Yii 2 的 yii2-imagine 扩展会自动探测服务器环境（GD 或 Imagick），直接调用底层库，出错时才报驱动缺失。
缩放：用 thumbnail() 还是 resize()？
别混淆这两个操作：thumbnail() 是“生成缩略图”，带智能比例控制和裁剪逻辑；resize() 是原始尺寸拉伸，不保持比例，容易变形。
-
thumbnail()默认行为是THUMBNAIL_INSET：等比缩放后居中填入目标框，留白（适合头像预览） - 加第四个参数
Image::THUMBNAIL_OUTBOUND才是裁剪：强制填满目标宽高，超出部分被切掉（适合封面图） -
resize()不在yii\imagine\Image静态类里——它属于Imagine\Image\ImageInterface实例方法，得先open()再链式调用，但一般没必要
示例：
use yii\imagine\Image;
// 等比缩放至最大边 300px，留白
Image::thumbnail('@webroot/uploads/photo.jpg', 300, 300)
->save('@webroot/thumbs/photo-small.jpg', ['quality' => 90]);
// 强制裁成 300×300，居中切
Image::thumbnail('@webroot/uploads/photo.jpg', 300, 300, Image::THUMBNAIL_OUTBOUND)
->save('@webroot/thumbs/photo-cover.jpg');
裁剪：用 crop() 要注意坐标原点和路径别名
crop($filename, $width, $height, $start) 的 $start 是左上角起点坐标 [x, y]，单位像素，不是百分比。常见错误是传了字符串或没校验原图尺寸，导致裁出黑块或空白。
- 务必确认原图宽高 ≥ 裁剪区域，否则
crop()可能静默失败或返回异常对象（不抛错，但save()失败） -
$filename必须是服务器绝对路径或带@webroot别名的路径；不能用$_FILES['file']['tmp_name']直接传——得先move_uploaded_file()存好再裁 - 如果要让用户自定义裁剪区域（如头像裁剪），前端传来的
x/y/w/h值，必须和服务端原图实际尺寸做比例换算，不能直接塞进crop()
示例（安全裁剪）：
$originalPath = '@webroot/uploads/photo.jpg';
$size = getimagesize(Yii::getAlias($originalPath));
if ($size[0] save('@webroot/thumbs/cropped.jpg');
质量与格式：save() 的 options 参数不是所有键都有效
save($path, $options) 支持的键取决于底层驱动（GD/Imagick）和输出格式。常见误区是以为 ['quality' => 80] 对 PNG 也生效——其实 PNG 不支持 quality，GD 下会被忽略，Imagick 下可能转成压缩 PNG（但不可控）。
- JPEG/PNG/WebP：只对 JPEG 和 WebP 有效；PNG 建议用
['png_compression_level' => 9]（0–9，数字越大压缩越狠） - WebP 格式需 PHP >= 7.4 + GD >= 2.3.0 或 Imagick，且
save()路径后缀必须是.webp - 不指定
$options时，默认 quality 是 75（GD）或 90（Imagick），差异明显，上线前务必实测
路径别名和权限：@webroot 不等于当前脚本目录
@webroot 指向的是 Web 服务器 DocumentRoot（通常是 frontend/web 或 backend/web），不是 runtime/ 或 uploads/ 这类自定义目录。如果把图片存在 @webroot/../uploads/，thumbnail() 能读，但浏览器无法直接访问——除非你额外配了 Nginx/Apache 别名。
- 生成的缩略图路径建议仍放在
@webroot下（如@webroot/thumbs/），确保 URL 可达 - 写入前检查目录是否存在且可写：
FileHelper::createDirectory()比mkdir(..., 0777, true)更 Yii 风格 - Windows 下路径分隔符反斜杠不影响
yii\imagine\Image，但Yii::getAlias()返回的是正斜杠，别自己拼串混用
真正麻烦的从来不是调哪个函数，而是原图尺寸不确定、用户上传乱七八糟的 MIME 类型、GD 缺失时没 fallback 提示、以及裁剪坐标从 JS 传过来漏了校验——这些地方一漏，线上就是白图或 500。
