Linux下Nginx配置Brotli极致压缩详细教程

许多教程在介绍 Nginx 启用 Brotli 压缩时，往往只告诉你添加 brotli on 即可。但在实际部署中，远没有这么简单——直接写入配置，大概率会抛出 unknown directive "brotli" 错误。本质上，Brotli 并非 Nginx 的内置功能，必须先编译对应模块，再根据业务场景调整参数，否则所谓的“极致压缩”只能停留在理论层面。

下面先厘清几个关键判断点。

确认 ngx_brotli 模块是否已成功编译进 Nginx

仅仅从 GitHub 克隆了 ngx_brotli 仓库，或者在宝塔面板点击了“添加模块”，并不代表模块已真正生效。验证的核心只有两条：

• 执行 nginx -V 2>&1 | grep with-http_brotli_module，有输出才说明 configure 阶段确实注入了该模块
• 运行 nginx -t 后不出现 unknown directive "brotli"，才代表基础校验通过
• OpenResty 用户必须选用与当前版本匹配的 ngx_brotli 分支（例如 OpenResty 1.21.x 对应 openresty 分支），混用会导致 make 失败
• 宝塔用户不宜直接 patch 已安装的二进制文件，更稳妥的方案是：卸载 → 编译安装 → 添加自定义模块

在 http 块中启用 brotli 并避免与 gzip 冲突

brotli on 写入 server 或 location 块基本无效，Nginx 会直接忽略。正确做法是将其置于 http 块的顶层，并同时显式关闭 gzip：

• brotli on 和 gzip off 必须成对出现，顺序无关紧要，但建议紧挨着写在 http 块起始位置
• brotli_static on 仅检查同名的 .br 文件（如 app.js.br），既不生成新压缩文件也不降级处理；若需要对动态 JSON 或 HTML 进行实时压缩，应设置 brotli_static off，并在对应 location 中再次声明 brotli on
• 不要依赖“自动协商”——客户端若未发送 Accept-Encoding: br，服务端绝不会返回 Content-Encoding: br

常见的踩坑点在于：许多人以为写上 brotli on 就万事大吉，结果用浏览器查看网络请求，发现仍是 gzip 编码。问题大多出在指令所在层级不对，或未关闭 gzip 导致两者冲突。

按资源类型分层设置 brotli_comp_level 与 brotli_min_length

全局统一设置 brotli_comp_level 11 会严重拖慢 TTFB，尤其在高 QPS 的接口上。经验表明，应根据场景做分级配置：

• 动态内容（API JSON、模板 HTML）：brotli_comp_level 1–4 即可，压缩耗时可降低约 60%，而压缩率仍优于 gzip 9
• 前端构建产物（.js/.css）：brotli_comp_level 5–6 较为均衡，压缩率约 63%，在 iOS/Android 上的解压延迟不超过 8ms
• 长期不变的静态资源（SVG、字体、reset.css）：使用 brotli_comp_level 8–11 配合 brotli_static on，前提是构建阶段已生成对应的 .br 文件
• brotli_min_length 建议设为 1024（1KB），避免小响应（如空 JSON）频繁触发 CPU 压缩

预压缩文件权限与 MIME 类型必须严格匹配

brotli_static on 属于“静默失败”型配置——如果文件存在但权限不正确，或 brotli_types 漏写了 MIME 类型，Nginx 会直接忽略该功能，也不会 fallback 到 gzip。因此务必注意：

• 构建阶段生成 .br 文件：Vite 使用 vite-plugin-compression，Webpack 使用 compression-webpack-plugin，并指定 algorithm: 'brotliCompress'
• brotli_types 必须与实际 .br 文件的 MIME 类型完全一致，例如 application/javascript 不能误写为 text/javascript
• .br 文件的权限需设为 644，确保 Nginx worker 进程可读取；否则日志中无任何提示，请求会直接走未压缩路径
• 保留 gzip on 作为兜底方案——尽管现代浏览器对 Brotli 的支持率已超过 98%，仍有部分监控工具或内网爬虫依赖 gzip

真正的难点不在于写几行配置，而在于将模块编译、MIME 匹配、预压缩生成、权限控制这四个环节串联成一个完整的闭环。遗漏任何一环，所谓的“极致压缩”就只剩下一个 Content-Encoding: br 的虚假表象，看上去美观却无法真正提升性能。