Nginx 模块配置中如何加载 Brotli 压缩模块替换经典 Gzip

作者：袖梨 2026-08-16

Nginx需手动编译集成ngx_brotli模块才能启用Brotli压缩，其与Gzip共存而非替代；须配置brotli on、合理设置brotli_types和brotli_min_length，并仅在HTTPS下生效。

Nginx 本身不内置 Brotli 支持，不能通过简单开关“替换”Gzip，而是要在保留 Gzip 的前提下，额外加载并启用 Brotli 模块——现代浏览器会自动按 Accept-Encoding: br,gzip 优先级选择最优压缩，Brotli 实际上是“叠加增强”，不是“替代卸载”。

必须先编译集成 ngx_brotli 模块

Nginx 最新主线（含 v1.25+）至今未原生支持 Brotli，必须手动引入 google/ngx_brotli 并重新编译：

源码部署用户：
1. 下载对应 Nginx 版本源码 + 克隆 ngx_brotli
2. ./configure 时添加 --add-module=/path/to/ngx_brotli（推荐动态模块 --add-dynamic-module）
3. make && make install
宝塔用户：
1. 卸载当前 Nginx（建议先做系统快照）
2. 软件商店 → Nginx → 编译安装 → 添加自定义模块 → 指向 /www/server/ngx_brotli
3. 提交后等待编译完成
验证是否成功：
1. nginx -V 2>&1 | grep with-http_brotli_module → 有输出即集成成功
2. nginx -t 不报 unknown directive "brotli" 错误

在配置中启用 Brotli（不干扰 Gzip）

Brotli 和 Gzip 可共存，无需关闭原有 gzip 配置。关键是要把 Brotli 配置放在 http { ... } 块内，并确保以下几项：

brotli on; —— 显式开启，否则不生效
brotli_static off; —— 必须关掉，否则会跳过动态压缩、只查 .br 文件（多数场景不需要预压缩）
brotli_types 列出你实际返回的文本 MIME 类型，例如：
```
text/plain text/css application/javascript application/json text/html image/svg+xml
```
（二进制类型如 image/jpeg、font/woff2 不用加）
brotli_min_length 1024; —— 小于 1KB 的响应不压缩，避免 CPU 白耗（默认仅 20 字节，太低）