SimpleImage 需手动配置GD扩展、EXIF方向校正及语义明确的缩放裁剪操作，否则易导致图片变形、旋转错乱或静默失败；务必确认GD启用、调用autoOrient()、区分resize()/thumbnail()/bestFit()、显式设置WebP/AVIF质量参数。
SimpleImage 不是“开箱即用”的零配置工具——它依赖 GD 扩展，且默认不自动处理 EXIF 方向、不校验输入路径合法性、不区分缩放与裁剪语义。直接调用 resize() 或 thumbnail() 很可能产出旋转错乱、拉伸变形或静默失败的图片。
GD 扩展没启用？SimpleImage 会直接报错
绝大多数 PHP 环境（尤其是 Docker 或新版 Alpine 镜像）默认不带 GD，new SimpleImage() 会抛出 Class 'GdImage' not found 或更模糊的 Call to undefined function imagecreatefromjpeg()。
- 运行
php -m | grep gd确认已加载；若无输出，需安装：apt-get install php-gd（Debian/Ubuntu）或apk add php82-gd（Alpine） - PHP 8.0+ 要求 GD 函数返回
GdImage对象而非 resource，旧版SimpleImage（如 v3.x 之前）可能不兼容 —— 务必用composer require claviska/simpleimage:^4.0 - Windows 用户注意：PHP.ini 中需取消注释
extension=gd，并确认libpng.dll、libjpeg.dll在系统 PATH 中
thumbnail() 和 resize() 完全不是一回事
新手常把二者混用，结果头像被拉宽、商品图被裁掉关键信息。它们底层逻辑截然不同：
-
resize(300, 200)：强制设为 300×200，不管原始比例 —— 图片必然变形 -
bestFit(300, 200)：等比缩放，使图片完全放入 300×200 区域内，留白区域需手动填充（pad()） -
thumbnail(300, 200, 'center')：先等比缩放到最小边 ≥ 目标尺寸，再从中心裁出 300×200 —— 无拉伸，但有裁剪
电商主图建议用 bestFit() + pad('white')；用户头像必须用 thumbnail() 并显式指定锚点（如 'top left' 避免裁掉人脸）。
EXIF 方向错乱？别跳过 autoOrient()
手机拍的照片常含 Orientation 标签，浏览器能自动纠正，但 SimpleImage 加载后默认忽略 —— 导致上传后图片逆时针转 90° 或上下颠倒，且无任何错误提示。
- 必须在
new SimpleImage($path)后立即调用：$image->autoOrient() - 该方法仅读取并应用 EXIF 中的旋转指令，不改变原始文件，也不影响后续操作链
- 如果用
fromData()或 URL 加载图片，EXIF 可能已丢失 —— 此时autoOrient()无效，需前端上传时预处理
保存 WebP/AVIF 时质量参数写错，文件体积反而更大
toFile('out.webp', 'image/webp', $quality) 的第三个参数不是布尔值，也不是百分比字符串 —— 它是整数 0–100，且默认值（80）对多数场景偏高。
- WebP：70–75 质量即可满足网页显示，体积比 JPEG 小 30% 以上；设为 90+ 时编码耗时陡增，体积收益趋近于零
- AVIF：需额外传
['quality'=>75, 'speed'=>6]，speed范围 0（最慢/最优）到 10（最快/压缩差），默认 4；设为 10 可提速 3 倍，但体积增大约 15% - 省略质量参数时，JPEG 默认 75，WebP 默认 80，AVIF 默认 50 —— AVIF 默认值偏低，务必显式设置
真正容易被忽略的是：所有输出操作（toFile、toScreen）前，SimpleImage 不做任何格式兼容性检查。传入 GIF 动画调 toFile('x.webp')，只会保存第一帧 —— 没警告，也没报错。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
