Nginx开启Brotli压缩教程详解

Nginx原生不支持Brotli压缩，必须手动编译集成ngx_brotli模块并严格配置才能生效——仅克隆源码或宝塔中误选“一键安装”而未勾选“编译安装”会导致模块形同虚设；验证需通过`nginx -V | grep with-http_brotli_module`确认编译集成，并用`curl -H "Accept-Encoding: br" -I`实测HTTPS响应头是否返回`Content-Encoding: br`，同时务必在http块顶层启用`brotli on`、关闭`gzip off`避免冲突，配合`brotli_static on`优先服务预压缩的`.br`文件（推荐构建时生成），合理设置`brotli_comp_level 4–6`兼顾性能与压缩率，否则极易因配置错位、作用域错误、CDN干扰或HTTP协议限制导致Brotli完全失效。

直接说结论：Nginx 本身不支持 Brotli，必须手动编译 ngx_brotli 模块，且配置不当会导致 Content-Encoding: br 不生效、甚至和 gzip 冲突或压根不压缩。

确认 Nginx 是否已加载 ngx_brotli 模块

光装了模块源码没用，得确认它真被编译进 Nginx 可执行文件里。运行以下命令：

nginx -V 2>&1 | grep -o with-http_brotli_module

有输出才说明模块已集成；若无输出，或执行 nginx -t 报错 unknown directive "brotli"，就代表模块未启用。常见误区是只 clone 了 ngx_brotli 但没重新 configure + make install，或者宝塔用户点了“添加模块”却没选“编译安装”——直接点“一键安装”默认不带第三方模块。

• OpenResty 用户注意：必须用对应 OpenResty 版本的 ngx_brotli 分支，混用会编译失败
• 宝塔用户更推荐走“软件商店 → Nginx → 卸载 → 编译安装 → 添加自定义模块”路径，别试图 patch 已安装的二进制
• 验证成功后，nginx -V 输出中应同时含 --add-module=/path/to/ngx_brotli 和 with-http_brotli_module

brotli on 必须放在 http 块，且要关掉 gzip 冲突

brotli 指令作用域有限，写在 server 或 location 块里可能被忽略（尤其当上级 http 块没启用时）。最稳妥写法是统一放在 http 块顶部，并显式禁用 gzip 的干扰：

# http { ...
brotli on;
brotli_comp_level 6;
brotli_types text/plain text/css application/javascript application/json text/xml image/svg+xml;
brotli_static on;
gzip off;  # 关键：不关掉 gzip，浏览器可能随机选 gzip 或 br，无法稳定生效
}

• brotli_static on 表示优先查找同名 .br 文件（如 app.js.br），适合 Vue/React 构建后预压缩场景
• 若想动态压缩（比如后端吐 JSON），则需设 brotli_static off，并确保 location 块内也写了 brotli on
• 不要相信“gzip 和 brotli 可共存自动降级”的说法——现代浏览器收到 Accept-Encoding: br,gzip 时，Nginx 默认按配置顺序选第一个启用的压缩方式，不自动协商

客户端必须发 br，服务端才回 br

Brotli 不是“开个开关就全局生效”，它依赖请求头明确声明支持。用 curl 测试最准：

curl -H "Accept-Encoding: br" -I https://yoursite.com/app.js

响应头中必须出现 Content-Encoding: br 才算成功。常见失效原因：

• HTTP 站点不会触发浏览器发送 br —— Chrome/Firefox/Safari 只在 HTTPS 下才在 Accept-Encoding 里加 br
• CDN（如 Cloudflare）或反向代理提前解压并重写响应头，建议先绕过 CDN 直连 Nginx 测试
• 后端（如 PHP-FPM）已设置 zlib.output_compression=On 或输出了 Content-Encoding，Nginx 就不会再压缩
• brotli_min_length 设得太低（如默认 20 字节）会导致大量小响应被压缩，徒增 CPU 开销；建议设为 1024 或更高

Vue/React 项目务必生成 .br 预压缩文件

仅靠 Nginx 动态压缩对 JS/CSS 效果有限，真正省流量靠的是构建时生成 .br 文件 + brotli_static on。以 Vite 为例，在 vite.config.ts 中加：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { compression } from 'vite-plugin-compression2'

export default defineConfig({
  plugins: [
    react(),
    compression({
      algorithm: 'brotliCompress',
      ext: '.br'
    })
  ]
})

• Webpack 用户可用 compression-webpack-plugin，注意 algorithm: 'brotliCompress' 和 filename: '[path][base].br'
• 生成后检查 dist 目录是否真有 index.html.br、assets/index.xxxx.js.br 等文件
• Nginx 查找 .br 文件是大小写敏感的，文件名必须完全匹配（包括大小写和扩展名）

最后提醒一句：Brotli 压缩比虽高，但 brotli_comp_level 11 会让单核 CPU 在高并发时卡住，生产环境建议用 4–6；而 brotli_static on 这条指令，很多人复制配置时漏掉，结果白配了。

到这里，我们也就讲完了《Nginx开启Brotli压缩教程详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于Linux的知识点！