ThinkPHP自带think\Image类crop()方法参数顺序为width、height、x、y，传反会导致空白图或“Invalid dimensions”错误；务必校验x+width≤原图宽且y+height≤原图高。
ThinkPHP 自带 think\Image 类裁剪图片时参数顺序别搞反
传错顺序是空白图或 Cannot crop image. Invalid dimensions. 错误的最常见原因。crop 方法签名是 crop($width, $height, $x, $y)，不是 crop($x, $y, $width, $height)。
实际操作中容易下意识按「坐标+尺寸」理解，结果把宽高传成 0 或负数，GD 就直接返回空资源。
- 务必先用
$image->width()和$image->height()校验原始图尺寸，确保$x + $width width()且$y + $height height() - 从左上角开始裁 200×150：正确写法是
$image->crop(200, 150, 0, 0) - 想从 (80, 60) 开始裁，却写了
$image->crop(80, 60, 200, 150)→ 实际裁的是宽 80、高 60、起点 (200, 150)，大概率越界
缩略图生成用 thumb() 但结果不是固定尺寸？看清楚缩放模式
thumb(150, 150) 默认走的是 \think\Image::THUMB_SCALING（等比例缩放），所以输出图宽高不一定是 150×150，而是「最长边 ≤ 150」的等比图。要强制固定尺寸，必须显式指定模式。
比如要生成严格 150×150 的缩略图，得用：
立即学习“PHP免费学习笔记（深入）”；
$image->thumb(150, 150, \think\Image::THUMB_FIXED)->save('./thumb.jpg');
其他常用模式：
-
\think\Image::THUMB_CENTER：等比缩放后居中裁剪到目标尺寸 -
\think\Image::THUMB_FILLED：等比缩放后填充背景色（默认黑）至目标尺寸 -
\think\Image::THUMB_NORTHWEST：从左上角开始裁，不缩放直接切
注意：THUMB_FIXED 会拉伸变形，THUMB_CENTER 才是多数头像场景真正需要的。
处理前端 cropper.js 传来的 base64 图片，别碰 $request->file()
前端用 cropper.js 调 getCroppedCanvas().toDataURL() 后 POST 到后端，字段名通常是 image_data，不是文件上传字段。此时 $request->file('image_data') 一定为 null —— 它只解析 multipart 表单里的 type="file" 字段。
正确做法是：
- 用
$request->param('image_data')拿到 base64 字符串 - 用
str_replace('data:image/', '', $base64)去掉前缀，再按分号拆出 MIME 和数据体 - 用
base64_decode()解码得到二进制图像数据，再喂给 GD：imagecreatefromstring($binary) - 如果前端没做旋转合并（即未调
getCroppedCanvas()而是直接读原图 canvas），你得手动用imagerotate()校正，否则裁出来是歪的
绕过 think\Image 直接用 GD 更可控，尤其涉及旋转+裁剪组合操作时。
上传后立刻裁剪，路径和权限问题比逻辑更常卡住流程
ThinkPHP 的 $file->move() 返回的是 think\File 对象，它的 getRealPath() 才是真实磁盘路径；getPathname() 可能只是临时上传路径（如 /tmp/phpXXXXXX），直接传给 Image::open() 会报文件不存在。
保存裁剪图前必须确认目标目录可写：
- 用
is_writable($dir)检查，不可写就mkdir($dir, 0755, true) - Windows 下路径分隔符统一用
DIRECTORY_SEPARATOR，别硬写/或\ - 裁剪图若存到
public/uploads/，URL 要对应拼/uploads/xxx.jpg，不能漏/public/前缀（Nginx/Apache 配置通常只映射 public 目录） - 文件名必须唯一，建议用
md5_file($real_path) . '.' . $ext或时间戳+随机字符串，避免覆盖和 XSS
GD 对 PNG 透明通道在 PHP 8.1+ 有兼容性变化，测试阶段优先用 JPG 验证流程是否通，再切回 PNG。
