intervention image 安装后 image 类找不到，主因是未注册服务提供者或误用 v3 版本的弃用 facade；laravel 9+ 需手动注册 imageserviceproviderlaravelrecent 并使用 imagemanager 而非 facade。
Intervention Image 安装后 Image 类找不到？
常见错误是安装了 intervention/image 但没注册 Laravel 的服务提供者，或者用了新版（v3）却照着旧文档写。Laravel 9+ 默认不自动发现包，必须手动注册。
- 运行
composer require intervention/image后，检查是否已执行php artisan vendor:publish --provider="Intervention\Image\ImageServiceProviderLaravelRecent" - 确认
config/app.php中providers数组包含Intervention\Image\ImageServiceProviderLaravelRecent::class - 别用
Intervention\Image\Facades\Image—— v3 已弃用 Facade，改用依赖注入或ImageManager实例 - v3 默认使用
gd驱动；若要换imagick，需在配置中显式指定，并确保系统已安装对应扩展
上传图片后裁剪并保存到 storage 目录
直接操作 $_FILES 或原始路径容易出错，应走 Laravel 的 UploadedFile 流程 + ImageManager 解码再处理。
- 先调用
$request->file('avatar')->store('temp')存临时文件，拿到相对路径如temp/abc.jpg - 用
ImageManager::read(storage_path('app/' . $path))加载，避免路径拼错（storage_path()返回绝对路径） - 裁剪推荐用
crop()而非fit()：前者按坐标裁，后者强制缩放+居中切，容易失真 - 保存时用
$image->save(storage_path('app/avatars/cropped_' . $filename))，别漏storage_path()—— 直接写avatars/...会存到项目根目录
生成响应式头像：不同尺寸裁剪共用一张原图
不要为每个尺寸重复读取、解码、裁剪原图，性能差且易触发内存限制。
- 用
ImageManager::read()一次加载原图，然后链式调用clone()+resize()+crop() - 例如：先
$base = ImageManager::read($src)，再$thumb = $base->clone()->resize(100, 100)->crop(100, 100, 0, 0) - 注意
crop(x, y, width, height)参数顺序：不是宽高优先，而是目标宽、高、起始 x、起始 y - 如果前端需要 WebP 格式，用
$image->encode('webp', 80)，但得确认服务器 PHP 编译时启用了 WebP 支持（gd_info()查看WebP Support是否为 true）
Intervention\Image\Exception\NotSupportedException 怎么回事
这错误基本等于“你传了个它不认识的格式”，比如上传了 .heic、.avif，或 GD 扩展压根不支持当前图片类型。
- 先用
getimagesize($path)检查 MIME 类型，过滤掉image/heic、image/avif等非标准类型 - GD 不支持 WebP 写入（只读），所以
encode('webp')在 GD 下会报这个错；换 Imagick 驱动可解 - Mac 上传的 HEIC 图片，浏览器可能自动转成 JPEG，但部分 iOS 版本仍会直传 HEIC —— 必须在控制器开头拦截并拒绝
- 调试时打印
$image->mime()和getimagesize($path)[2]对比，能快速定位格式断层点
裁剪逻辑看着简单，但真正上线后卡住你的往往不是 API 调用，而是路径权限、GD/Imagick 驱动差异、HEIC 兼容性这些边缘情况。别跳过 getimagesize 和 gd_info 这两行检查。
