Nginx启用Brotli需三步闭环：先编译集成ngx_brotli模块并验证（nginx -V查with-http_brotli_module），再在http或location块中配置brotli on、brotli_static off及精准brotli_types，最后按场景调优brotli_comp_level（动态3–5、静态6–7）和brotli_min_length等参数。
要让 Nginx 支持 Brotli 压缩并发挥其更高压缩比的优势，关键不在“加一行配置”就能生效，而在于三步闭环：先确认模块可用、再精准启用动态压缩、最后按资源特性调优参数。Brotli 对 HTML/JS/CSS 等文本类资源的压缩率通常比 Gzip 高 17–25%，尤其在低级别（如 level 1）就能超越 Gzip 最高级别（level 9），但前提是配置真正落地且不被干扰。
确认 Nginx 已集成 Brotli 模块
Nginx 官方主线版本至今（v1.25+）仍不原生支持 Brotli，必须通过第三方模块 google/ngx_brotli 编译接入。验证是否成功集成有两个可靠方式：
- 执行
nginx -V 2>&1 | grep with-http_brotli_module，有输出说明已编译进内核 - 临时在配置中加入
brotli on;后运行nginx -t，若报错unknown directive "brotli"，则模块未加载
宝塔用户需先卸载当前 Nginx，再通过【编译安装】+【添加自定义模块】路径引入 /www/server/ngx_brotli；Docker 或手动部署用户需在 ./configure 中显式添加 --add-module=/path/to/ngx_brotli 并重新编译。
在 http 或 location 块中启用动态压缩
Brotli 动态压缩由 brotli on 触发，它对响应体实时编码，不依赖预生成的 .br 文件。因此以下两项必须同时满足：
-
brotli_static off—— 关键！设为on会跳过动态压缩，只查找静态 .br 文件 -
brotli_types明确列出需压缩的 MIME 类型，例如：text/plain text/css application/javascript application/json text/html image/svg+xml
推荐将配置放在 http 块顶层（全局生效），或更精细地放在 location 块中实现目录级控制，比如只为 /api/ 启用 JSON 压缩：
brotli on;
brotli_types application/json text/plain;
brotli_comp_level 4;
brotli_static off;
}
按场景调优核心压缩参数
Brotli 提供 0–11 共 12 级压缩质量，不同级别对 CPU 和压缩率影响显著，不能一概设为最高：
-
动态内容（API 返回、PHP 渲染页）：推荐
brotli_comp_level 3–5，兼顾响应延迟与带宽节省 -
静态资源（JS/CSS/HTML）：可设
6–7，服务器压力可控时收益明显 - 极小文件（：用
brotli_min_length 20避免无效开销 -
大文件流式传输：可增大
brotli_window 1m提升长距离重复字符串识别能力
注意：Brotli 不会覆盖已含 Content-Encoding 的响应（如后端 PHP 自行启用了 zlib 输出压缩），务必关闭上游压缩以避免冲突。
验证是否真实生效
配置重载后，用终端命令快速验证：
-
curl -H "Accept-Encoding: br" -I https://yoursite.com/test.js—— 查看响应头是否有Content-Encoding: br - 浏览器开发者工具 Network 面板中检查任意文本资源的 Response Headers
- 若返回
gzip或为空，优先排查：CDN 是否劫持了响应头、反向代理是否提前解压、客户端是否真的声明支持br
建议初期保留 Gzip 配置作为后备（gzip on），确保不支持 Brotli 的旧客户端仍能获得基础压缩。
