ngx_http_image_filter_module支持Nginx层轻量级图片处理，需编译启用并依赖libgd，仅支持JPEG/GIF/PNG；通过resize/crop指令实现缩放与裁剪，配合参数校验、防盗链和缓存优化保障生产可用性。
使用 ngx_http_image_filter_module 可以在 Nginx 层直接处理图片，实现轻量级、低延迟的在线裁剪与缩略图分发，无需后端参与。该模块依赖于 libgd，需在编译 Nginx 时启用（或确认已加载），且仅支持 JPEG、GIF、PNG 格式。
确认模块可用并启用
运行 nginx -V 2>&1 | grep -o with-http-image-filter-module，若输出存在说明已编译进内核。若未启用，需重新编译 Nginx 并添加 --with-http_image_filter_module 参数。模块默认不自动加载，需在配置中显式调用：
- 确保
http块中包含load_module modules/ngx_http_image_filter_module.so;（动态模块方式）或直接静态链接 - 检查
libgd已安装（如 Ubuntu 上执行apt install libgd-dev） - 重启 Nginx 后用
curl -I http://your-domain/test.jpg?width=100&height=100测试是否返回 200 + 正确 Content-Type
配置基础缩略图服务（resize）
通过 image_filter resize 按比例缩放图片，保持宽高比。适用于头像、列表图等需统一尺寸但不严格裁切的场景：
- 在
location块中匹配图片路径（如location ~* ^/img/(.+)\.(jpg|jpeg|png|gif)$） - 使用
image_filter resize $arg_width $arg_height;读取 URL 参数控制尺寸 - 添加
image_filter_jpeg_quality 85;控制压缩质量（默认 95，过高影响性能） - 务必设置
expires 7d;和add_header Cache-Control "public, immutable";提升缓存效率
实现智能裁剪（crop）与居中截取
image_filter crop 会按指定宽高强制裁剪，从图片中心开始截取。适合封面图、卡片图等需精确尺寸的场景：
- 将
resize替换为image_filter crop $arg_width $arg_height; - 注意：原图必须 ≥ 目标尺寸，否则返回 415 错误；可配合
image_filter_buffer调大内存缓冲（如image_filter_buffer 10M;）以支持大图 - 若需自定义裁剪起点（非居中），该模块不支持；应改用
thumbor或 OpenResty + lua-resty-image 等方案 - 建议搭配
try_files $uri @fallback;，当缩略图不存在或处理失败时回源原始图
URL 设计与安全控制
公开暴露 image_filter 接口存在被恶意刷图、DDoS 或盗链风险，需限制参数范围与来源：
- 用
map限定允许的尺寸组合（如只允许 100x100、300x200、800x600），拒绝非法width/height值 - 添加
valid_referers none blocked server_names *.yourdomain.com;配合if ($invalid_referer) { return 403; }防盗链 - 对参数做基本校验：用
if ($arg_width !~ ^[0-9]{1,4}$) { return 400; }防止超大值耗尽内存 - 生产环境避免直接暴露原始图目录，建议将原图放在
alias或root不可遍历的路径下，并通过内部 location 处理
不复杂但容易忽略：每次图片请求都会触发实时解码与重编码，CPU 开销明显。上线前务必压测，结合 CDN 缓存和本地磁盘缓存（如 proxy_cache）降低重复处理。对于高并发或高分辨率需求，建议生成后持久化缩略图，而非纯实时处理。
