必须使用 liip/imagine-bundle 集成 imagine 库，因其提供依赖注入、配置驱动、filter 链式处理及缓存协同能力；仅装 imagine/imagine 会导致手动管理路径、缓存键和响应头，实为重复造轮子。
Imagine 库本身不提供 Symfony 集成层，官方也没有 imagine-bundle。直接 require imagine/imagine 后手动 new Imagick 或 Gd 实例虽能用，但会丢失依赖注入、配置复用、缓存联动等关键能力——必须通过社区维护的 liip/imagine-bundle 接入。
为什么不能只装 imagine/imagine
纯库没有服务定义、无配置驱动、不支持 filter 链式处理、无法与 Symfony 的 cache 系统（如 cache.adapter.filesystem）自动协同。你手写一个 new \Imagine\Gd\Imagine()，后续想加水印、改尺寸、存 CDN，就得自己拼路径、管缓存键、处理异常响应头——这不是集成，是重造轮子。
正确做法是：
- 运行
composer require liip/imagine-bundle - 在
config/bundles.php中启用Liip\ImagineBundle\LiipImagineBundle::class => ['all' => true] - 执行
php bin/console liip:imagine:cache:resolve /uploads/photo.jpg测试基础链路
liip/imagine-bundle 的核心配置项
它把 Imagine 封装为可配置的 filter 管道，所有图像操作都通过命名 filter 触发。关键配置在 config/packages/liip_imagine.yaml：
liip_imagine:
resolvers:
default:
web_path: ~
filter_sets:
my_thumb:
cache: default
data_loader: default
post_processors: []
filters:
thumbnail: { size: [120, 90], mode: outbound }
background: { size: [120, 90], color: '#ffffff' }
注意点：
-
thumbnail的mode值只能是outbound（裁剪）或inset（缩放），填错会静默失败 -
background必须在thumbnail之后，顺序决定执行流 - 若用
imagick，确保系统已安装 ImageMagick 二进制且 PHP 扩展imagick已启用，否则日志里只报Unable to create image resource，不提示缺扩展
在 Twig 和 Controller 中调用 filter
生成带签名的 URL 是最常用场景，Bundle 自动处理缓存和重定向：
Twig 中：<img src="%7B%7B%20'/uploads/photo.jpg'%7Cimagine_filter('my_thumb')%20%7D%7D">
Controller 中：$this->get('liip_imagine.cache.manager')->getBrowserPath('/uploads/photo.jpg', 'my_thumb')
注意：
- 路径必须是 Web 可访问的相对路径（如
/uploads/xxx），不是public/uploads/或绝对文件系统路径 - 首次访问时返回 302 重定向到生成后的图片，第二次才 200 直出——这是设计行为，不是 bug
- 如果页面显示空白图，先检查浏览器开发者工具 Network 标签页里该 URL 是否返回 500；常见原因是源图不存在或权限不足，Bundle 默认不抛异常，只记录 warning 到日志
自定义 filter 或处理器要绕过 Bundle 的自动机制
比如想加文字水印，Bundle 不内置该 filter，需注册自定义服务：
先写类：App\Imagine\Filter\WatermarkFilter，实现 Liip\ImagineBundle\Imagine\Filter\FilterInterface；再在 services.yaml 中标记 tags: [{ name: 'liip_imagine.filter' }]；最后在 filter_sets 里引用 watermark: { text: '©2024' }。
难点在于：
- Filter 类的
apply()方法接收的是Imagine\Image\ImageInterface，不是原始二进制，别试图用file_get_contents - 字体路径必须用
%kernel.project_dir%/public/fonts/xxx.ttf，不能用@App或__DIR__ - 自定义 filter 不参与 Bundle 的缓存键自动计算，需手动在
getCacheKey()里拼入参数，否则不同文字水印会共用同一缓存文件
真正卡住人的往往不是代码怎么写，而是缓存键没重算、字体路径不对、或者忘了在 services.yaml 里加 tag —— 这些地方不报错，只让图片不生效。
