如何使用 ngx_http_image_filter_module 实现图片的在线裁剪与缩略图分发-Nginx-PHP中文网

ngx_http_image_filter_module支持Nginx层轻量级图片处理，需编译启用并依赖libgd，仅支持JPEG/GIF/PNG；通过resize/crop指令实现缩放与裁剪，配合参数校验、防盗链和缓存优化保障生产可用性。

如何使用 ngx_http_image_filter_module 实现图片的在线裁剪与缩略图分发

使用 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 处理