# Ngx 第三方库 ngx\_brotli

## **CentOS 7、8 安装并加载 Nginx 模组 ngx\_brotli 然后启用 brotli 压缩** <a href="#centos-7-e3-80-818-e5-ae-89-e8-a3-85-e5-b9-b6-e5-8a-a0-e8-bd-bd-nginx-e6-a8-a1-e7-bb-84-ngx_brotli-e" id="centos-7-e3-80-818-e5-ae-89-e8-a3-85-e5-b9-b6-e5-8a-a0-e8-bd-bd-nginx-e6-a8-a1-e7-bb-84-ngx_brotli-e"></a>

项目地址：[Github 仓库地址](https://link.juejin.cn/?target=https%3A%2F%2Fgithub.com%2Fgoogle%2Fngx_brotli)

## ngx\_brotli <a href="#ngx_brotli" id="ngx_brotli"></a>

Brotli是一种通用无损压缩算法，它结合了LZ77算法的现代变体、Huffman编码和二阶上下文建模来压缩数据，其压缩比可与目前可用的最佳通用压缩方法相媲美。它在速度上与 deflate 相似，但提供了更高的压缩率。

**注意：该压缩编码仅可用于 https 通信。**

ngx\_brotli 包含两个模块：

* `ngx_brotli filter module` - 用于动态压缩响应体。
* `ngx_brotli static module` - 用于使用预压缩的 .br 文件进行服务（静态站点）。

### 安装方法 <a href="#e5-ae-89-e8-a3-85-e6-96-b9-e6-b3-95" id="e5-ae-89-e8-a3-85-e6-96-b9-e6-b3-95"></a>

#### 获取 ngx\_brotli <a href="#e8-8e-b7-e5-8f-96-ngx_brotli" id="e8-8e-b7-e5-8f-96-ngx_brotli"></a>

1. 确保你安装了 git，如果没有，使用命令安装：

```bash
yum -y install git
```

2. 从仓库获取 `ngx_brotli`

```bash
git clone https://github.com/google/ngx_brotli.git
```

如果服务器位于国内，建议使用镜像：

```bash
git clone https://gitee.com/xlsw/ngx_brotli.git
```

3. 初始化子模块

```bash
cd ngx_brotli $ git submodule update --init $ cd ~
```

#### 获取 Nginx 源码 <a href="#e8-8e-b7-e5-8f-96-nginx-e6-ba-90-e7-a0-81" id="e8-8e-b7-e5-8f-96-nginx-e6-ba-90-e7-a0-81"></a>

1. 如果你已经安装了 Nginx，请查看版本：

```bash
nginx -v
```

本示例已安装 nginx 版本为：

> nginx version: nginx/1.20.1

2. 获取并解压 Nginx 源码（将字符`x`替换为你的 Nginx 版本号，如未安装可自定义）

```bash
wget https://nginx.org/download/nginx-1.x.x.tar.gz && tar zxvf nginx-1.x.x.tar.gz
```

本示例版本为 1.20.1，则命令为：

```bash
wget https://nginx.org/download/nginx-1.20.1.tar.gz && tar zxvf nginx-1.20.1.tar.gz
```

3. 清除垃圾文件

```bash
rm nginx-1.20.1.tar.gz
```

#### 安装 <a href="#e5-ae-89-e8-a3-85" id="e5-ae-89-e8-a3-85"></a>

以下两种方式选择一种即可，已通过 yum 源安装 Nginx 建议选择第一种 **动态模块加载**

**动态模块加载**

1. 安装编译所需环境

```bash
yum -y install pcre pcre-devel zlib zlib-devel openssl openssl-devel
```

2. 进入 Nginx 源码目录并编译子模块

官方文档说明为：

```bash
cd nginx-1.x.x $ ./configure --with-compat --add-dynamic-module=/路径/ngx_brotli $ make modules
```

本示例则使用（`ngx_brotli`已克隆到本地`~`目录下）：

```bash
cd ~/nginx-1.20.1 $ ./configure --with-compat --add-dynamic-module=../ngx_brotli $ make modules
```

3. 将生成的 .so 动态库移动到 Nginx 的 modules 目录（默认为`/etc/nginx/modules`）

```bash
cp objs/*.so /etc/nginx/modules
```

4. 为 .so 动态库文件添加权限

```bash
chmod 644 /etc/nginx/modules/*.so
```

5. 向 `nginx.conf` 中添加配置（添加至 http 块之上）

```bash
load_module modules/ngx_http_brotli_filter_module.so; 
load_module modules/ngx_http_brotli_static_module.so;
```

**模块静态编译并安装**

将第一行中的字符`x`替换为你上文中获取的 Nginx 源码版本号

```bash
cd nginx-1.x.x $ ./configure --add-module=/path/to/ngx_brotli $ make && make install
```

该操作将会直接将`ngx_brotli`编译并直接安装到 Nginx 中

#### 配置项 <a href="#e9-85-8d-e7-bd-ae-e9-a1-b9" id="e9-85-8d-e7-bd-ae-e9-a1-b9"></a>

**`brotli_static`**

* **语法：**`brotli_static on|off|always`
* **默认值：**`off`
* **上下文：**`http`, `server`, `location`

启用或禁用自动检查是否有`.br`预压缩文件是否存在，然后再使用；如果值为`always`则不会检查而直接使用预压缩文件。

**`brotli`**

* **语法：**`brotli on|off`
* **默认值：**`off`
* **上下文：**`http`, `server`, `location`, `if`

启用或禁用动态压缩响应体。

**`brotli_types`**

* **语法：**`brotli_types <mime 类型> [..]`
* **默认值：**`text/html`
* **上下文：**`http`, `server`, `location`

除了`text/html`外，还支持对特定的MIME类型进行动态压缩。特殊值`*`会匹配所有MIME类型，`Content-Type`为`text/html`的响应体将总是被压缩。

**`brotli_buffers`**

* **语法：**`brotli_buffers <number> <size>`
* **默认值：**`32 4k|16 8k`
* **上下文：**`http`, `server`, `location`

已被**弃用**，忽略该条配置项。

**`brotli_comp_level`**

* **语法：**`brotli_comp_level <级别>`
* **默认值：**`6`
* **上下文：**`http`, `server`, `location`

设置 Brotli 动态压缩质量`级别`，取值范围从`0`至`11`。取值越大但性能损耗越高，压缩比越高，建议默认。

**`brotli_window`**

* **语法：**`brotli_window <大小>`
* **默认值：**`512k`
* **上下文：**`http`, `server`, `location`

设置 Brotli 窗口`大小`，取值为`1k`, `2k`, `4k`, `8k`, `16k`, `32k`, `64k`, `128k`, `256k`, `512k`, `1m`, `2m`, `4m`, `8m`和`16m`。Gzip 压缩使用固定大小的`32k`窗口，这意味着 Brotli 窗口最多可以比 deflate 窗口大 512 倍。这种差异在 Web 服务器上下文中几乎无关紧要，因为大于 32KB 的文本文件是少数。

**`brotli_min_length`**

* **语法：**`brotli_min_length <长度>`
* **默认值：**`20`
* **上下文：**`http`, `server`, `location`

设置启用 Brotli 压缩的响应体最小`长度`，该值只会根据响应头中的`Content-Length`字段进行判断。

**变量**

`$brotli_ratio`：实现压缩比，原始响应大小和压缩响应大小之间的比率计算结果。

**示例配置**

```bash
brotli on;
brotli_comp_level 6;
brotli_static on;
brotli_types application/atom+xml application/javascript application/json application/rss+xml
             application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype
             application/x-font-ttf application/x-javascript application/xhtml+xml application/xml
             font/eot font/opentype font/otf font/truetype image/svg+xml image/vnd.microsoft.icon
             image/x-icon image/x-win-bitmap text/css text/javascript text/plain text/xml;
```

### 错误处理

\*\*如果 ngx make 出现错误\*\*

```pine
/opt/rh/devtoolset-8/root/usr/libexec/gcc/x86_64-redhat-linux/8/ld: cannot find -lbrotlienc
/opt/rh/devtoolset-8/root/usr/libexec/gcc/x86_64-redhat-linux/8/ld: cannot find -lbrotlicommon
collect2: error: ld returned 1 exit status
```

**\*\*处理方法\*\***

```bash
# Centos7
sudo yum install brotli brotli-devel

# Ubuntu
sudo apt-get update
sudo apt-get install libbrotli-dev
```

```
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://close.gitbook.io/yun-wei-bi-ji/centos/nginx/ngx-di-san-fang-ku-ngxbrotli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.