nginx image_filter模块支持轻量级实时图片处理，如缩放、裁剪和文字水印，但不支持格式转换、PNG透明水印及复杂图形水印；需手动编译启用，配置中用resize/crop/fit等指令控制，配合缓存避免性能损耗。
nginx 的 image_filter 模块可直接在 Web 服务器层对图片做轻量级实时处理，无需后端干预，适合静态图缩放、裁剪和简单水印（如文字水印）。但需注意：它不支持图片格式转换（如 JPG→WebP）、不支持透明 PNG 水印图叠加，也不支持复杂图形水印（如带透明度的 PNG logo）——这些必须交由后端或 CDN 图片处理服务完成。
启用与基础配置验证
确认 nginx 已编译含 --with-http_image_filter_module（主流发行版预装包通常不含，需自行编译或使用 OpenResty）。检查配置语法并重启：
- 在
http块中添加：load_module modules/ngx_http_image_filter_module.so;（动态加载，OpenResty 默认已内置） - 在
location中启用模块，例如匹配/img/下所有图片请求：location ~ ^/img/(.+)\.(jpg|jpeg|png|gif)$ {<br> image_filter resize 300 -;<br> image_filter_jpeg_quality 85;<br> alias /var/www/static/images/;<br>} - 访问
https://example.com/img/photo.jpg?width=400（若启用了image_filter_interlace on和参数解析）需配合自定义变量逻辑，原生模块不直接支持 URL 参数驱动 —— 此处建议用map或 Lua 扩展增强
实现固定尺寸缩放与质量控制
image_filter 支持三种缩放模式：resize（等比缩放至指定宽高内）、crop（等比缩放后居中裁剪）、fit（强制拉伸填充，不推荐）。常用组合如下：
-
image_filter resize 800 600;→ 宽 ≤800、高 ≤600，保持比例，不放大原图 -
image_filter crop 300 200;→ 先等比缩放到最小边 ≥300×200，再中心裁剪 -
image_filter_jpeg_quality 92;控制 JPG 输出质量（30–100），PNG 不生效 -
image_filter_buffer 10M;设置最大读取缓冲（默认 1M），避免大图报错 415
添加文字水印（仅限简单场景）
模块原生仅支持文字水印，通过 image_filter_transparency 配合 image_filter 指令链实现，但限制极多：
- 必须使用
image_filter rotate 0;触发水印渲染流程（这是隐藏机制） - 文字内容、颜色、位置需提前写死在配置中，例如：
image_filter_transparency on;<br>image_filter_text "© example.com" 12 #000000 10 10;<br>image_filter rotate 0;
- 字体路径需在编译时指定
--with-image-filter-font-path=/usr/share/fonts/dejavu/，且仅支持 TrueType 字体（.ttf） - 不支持自动换行、透明度调节、旋转文字；位置坐标为左上角偏移，非居中
替代方案建议（当需求超出模块能力）
若需 PNG logo 水印、自适应位置、格式转换或 URL 参数驱动（如 ?w=300&h=200&watermark=1），推荐以下路径：
- 用 OpenResty + lua-resty-image 库，在 nginx 层调用 Lua 处理，支持 GD/ImageMagick 后端
- 前端请求转发到专用图片服务（如 Thumbor、ImgProxy），它们提供完整 REST API 和安全签名机制
- CDN 层开启图片优化（Cloudflare Image Resizing、阿里云 IMG、腾讯云 CI），免运维且支持水印图、样式模板
- 静态图构建阶段预生成多尺寸 + 水印版本（Webpack + image-minimizer-webpack-plugin），适合内容稳定站点
不复杂但容易忽略：所有 image_filter 操作都发生在响应生成前，会增加 CPU 开销，务必搭配合理缓存策略（如 proxy_cache 或 CDN 缓存）避免重复处理同一张图。
