Nginx本身不支持Brotli，必须手动编译ngx_brotli模块并正确配置；仅克隆源码未重新编译安装、或宝塔未选“编译安装”均会导致brotli指令无效，需用nginx -V确认with-http_brotli_module输出且nginx -t无unknown directive错误。
直接说结论：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 { ...<br>brotli on;<br>brotli_comp_level 6;<br>brotli_types text/plain text/css application/javascript application/json text/xml image/svg+xml;<br>brotli_static on;<br>gzip off; # 关键：不关掉 gzip，浏览器可能随机选 gzip 或 br，无法稳定生效<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'<br>import react from '@vitejs/plugin-react'<br>import { compression } from 'vite-plugin-compression2'<br><br>export default defineConfig({<br> plugins: [<br> react(),<br> compression({<br> algorithm: 'brotliCompress',<br> ext: '.br'<br> })<br> ]<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 这条指令，很多人复制配置时漏掉，结果白配了。
