必须在源码编译时显式添加--with-http_image_filter_module参数，且需安装libgd开发包、与--with-http_ssl_module同时启用、通过nginx -v验证模块内建，缺一不可。
Nginx 源码编译启用 Image Filter 模块（即 ngx_http_image_filter_module）需要在配置阶段显式开启，因为它**不是默认内置模块**，且依赖外部图像处理库（libgd）。以下是关键步骤和注意事项：
确认依赖已安装
该模块依赖 libgd 及其开发头文件，需提前安装：
- Ubuntu/Debian：
sudo apt install libgd-dev - CentOS/RHEL：
sudo yum install gd-devel或sudo dnf install gd-devel - macOS（Homebrew）：
brew install gd
安装后可通过 pkg-config --exists gd 验证是否可用。若提示 not found，请检查 pkgconfig 路径或手动指定 --with-gd=PATH。
编译时启用模块
进入 Nginx 源码目录，执行 ./configure 时添加 --with-http_image_filter_module 参数：
./configure \
--with-http_image_filter_module \
--with-http_ssl_module \
--with-http_gzip_static_module \
... # 其他所需模块
⚠️ 注意：该模块必须与 --with-http_ssl_module 同时启用（因缩放/旋转等操作可能涉及 HTTPS 图片重写），否则 configure 会报错。
验证模块是否生效
编译安装后，运行 nginx -V 2>&1 | grep -o with-http_image_filter_module，若输出该字符串，说明模块已成功编译进二进制。
在配置文件中可使用如下指令测试：
location /img/ {
image_filter resize 200 150;
image_filter_jpeg_quality 85;
alias /var/www/images/;
}
重启 Nginx 后访问 /img/photo.jpg 即可触发实时缩略图生成（需确保源图存在且权限正确）。
常见问题提醒
- libgd 版本太低（如
- 模块不支持 WebP 输入（仅输出），输入格式限于 JPEG、GIF、PNG
- 若启用
image_filter rotate，需确保 libgd 编译时启用了 freetype 支持（用于文字水印，非必需但推荐） - 模块是同步阻塞式处理，高并发下慎用，生产环境建议配合缓存（如 proxy_cache）
