# ngx\_http\_image\_filter\_module

* [指令](#directives)
  * [image\_filter](#image_filter)
  * [image\_filter\_buffer](#image_filter_buffer)
  * [image\_filter\_interlace](#image_filter_interlace)
  * [image\_filter\_jpeg\_quality](#image_filter_jpeg_quality)
  * [image\_filter\_sharpen](#image_filter_sharpen)
  * [image\_filter\_transparency](#image_filter_transparency)
  * [image\_filter\_webp\_quality](#image_filter_webp_quality)

`ngx_http_image_filter_module` 模块（0.7.54+）是一个可以转换 JPEG、GIF、PNG 和 WebP 格式图像的过滤器。

此模块不是默认构建的，可以使用 `--with-http_image_filter_module` 配置参数启用。

> 该模块使用了 [libgd](http://libgd.org/) 库。建议使用该库的最新版本。
>
> WebP 格式支持出现在 1.11.6 版本中。要转换成此格式的图像，必须在编译 `libgd` 库时启用 WebP 支持。

## 示例配置 <a href="#example_configuration" id="example_configuration"></a>

```
location /img/ {
    proxy_pass   http://backend;
    image_filter resize 150 100;
    image_filter rotate 90;
    error_page   415 = /empty;
}

location = /empty {
    empty_gif;
}
```

## 指令 <a href="#directives" id="directives"></a>

### image\_filter

|       - | 说明                                                                                                                                                                                                                                                                                                                                                                                         |
| ------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|  **语法** | <p><strong>image\_filter</strong> <code>off</code>; <br><strong>image\_filter</strong> <code>test</code>;<br><strong>image\_filter</strong> <code>size</code>;<br><strong>image\_filter</strong> <code>rotate 90 \&#124; 180 \&#124; 270</code>;<br><strong>image\_filter</strong> <code>resize width height</code>;<br><strong>image\_filter</strong> <code>crop width height</code>;</p> |
|  **默认** | image\_filter off;                                                                                                                                                                                                                                                                                                                                                                         |
| **上下文** | location                                                                                                                                                                                                                                                                                                                                                                                   |

设置图片执行的转换类型：

* `off`

  关闭对 location 模块的处理
* `test`

  确保响应是 JPEG、GIF、PNG 或 WebP 格式的图片。否则，返回 415（不支持的媒体类型）错误。
* `size`

  以 JSON 格式输出图片的信息，例如：

  ```javascript
    { "img" : { "width": 100, "height": 100, "type": "gif" } }
  ```

  发生错误时，输出如下：

  ```javascript
    {}
  ```
* `rotate 90&#124;180&#124;270`

  将图片逆时针旋转指定的度数。参数值可以包含变量。此模式可以单独使用，也可以与调整大小和裁剪转换一起使用。
* `resize width height`

  按比例将图片缩小到指定的尺寸。要只指定一个维度，可以将另一个维度指定为 `-`。当发生错误，服务器将返回 415 状态码（不支持的媒体类型）。参数值可以包含变量。当与 `rotate` 参数一起使用时，旋转变换将在缩小变换**之后**执行。
* `crop width height`

  按比例将图片缩小到较大的一边，并裁剪另一边多余的边缘。要只指定一个维度，可以将另一个维度指定为 `-`。当发生错误，服务器将返回 415 状态码（不支持的媒体类型）。参数值可以包含变量。当与 `rotate` 参数一起使用时，旋转变换将在缩小变换**之前**执行。

### image\_filter\_buffer

|       - | 说明                                |
| ------: | --------------------------------- |
|  **语法** | **image\_filter\_buffer** `size`; |
|  **默认** | image\_filter\_buffer 1M;         |
| **上下文** | http、server、location              |

设置用于读取图片的缓冲区的最大大小。当超过指定大小时，服务器返回 415 错误状态码（不支持的媒体类型）。

### image\_filter\_interlace

|       - | 说明                                          |
| ------: | ------------------------------------------- |
|  **语法** | **image\_filter\_interlace** `on` \| `off`; |
|  **默认** | image\_filter\_interlace off;               |
| **上下文** | http、server、location                        |
|  **提示** | 该指令在 1.3.15 版本中出现                           |

如果启用此选项，图片最后将被逐行扫描。对于 JPEG，图片最终将采用**逐行 JPEG** 格式。

### image\_filter\_jpeg\_quality

|       - | 说明                                          |
| ------: | ------------------------------------------- |
|  **语法** | **image\_filter\_jpeg\_quality** `quality`; |
|  **默认** | image\_filter\_jpeg\_quality 75;            |
| **上下文** | http、server、location                        |

设置 JPEG 图片的转换质量。可接受的值范围在 1 到 100 之间。较小的值意味着较低的图片质量和较少的数据传输。最大的推荐值是 95，参数值可以包含变量。

### image\_filter\_sharpen

|       - | 说明                                    |
| ------: | ------------------------------------- |
|  **语法** | **image\_filter\_sharpen** `percent`; |
|  **默认** | image\_filter\_sharpen 0;             |
| **上下文** | http、server、location                  |

增加最终图像的清晰度。锐度百分比可以超过 100。零值将禁用锐化。参数值可以包含变量。

### image\_filter\_transparency

|       - | 说明                                             |
| ------: | ---------------------------------------------- |
|  **语法** | **image\_filter\_transparency** `on` \| `off`; |
|  **默认** | image\_filter\_transparency on;                |
| **上下文** | http、server、location                           |

定义在使用调色板指定的颜色转换 GIF 图像或 PNG 图像时是否保留透明度。透明度的丧失使图像的质量更好的。PNG 中的 alpha 通道透明度始终保留。

### image\_filter\_webp\_quality

|       - | 说明                                          |
| ------: | ------------------------------------------- |
|  **语法** | **image\_filter\_webp\_quality** `quality`; |
|  **默认** | image\_filter\_webp\_quality 80;            |
| **上下文** | http、server、location                        |
|  **提示** | 该指令在 1.11.6 版本中出现                           |

设置 WebP 图片的转换质量。可接受的值在 1 到 100 之间。较小的值意味着较低的图片质量和较少的数据传输。参数值可以包含变量。

## 原文档

<http://nginx.org/en/docs/http/ngx_http_image_filter_module.html>