nginx 默认不支持 brotli，需手动编译 ngx_brotli 模块并验证 nginx -v 和 nginx -t；启用时须在 http 块顶层配 brotli on 且 gzip off，精准设置 brotli_types、comp_level 和 min_length，并注意 https 要求及 cdn 干扰。
Nginx 默认不支持 Brotli，必须手动编译 ngx_brotli 模块并正确配置，否则所有 brotli 指令都会报 unknown directive 错误。
确认 Nginx 是否已集成 brotli 模块
光 clone 了 ngx_brotli 仓库或点了宝塔“添加模块”按钮，不代表模块真生效。关键验证步骤只有两个：
- 运行
nginx -V 2>&1 | grep with-http_brotli_module，有输出才说明编译时已注入 - 执行
nginx -t，不报unknown directive "brotli"才算通过 - OpenResty 用户必须用对应版本的
ngx_brotli分支，混用会导致make失败 - 宝塔用户别试图 patch 已安装的二进制，应走「卸载 → 编译安装 → 添加自定义模块」路径
在 http 块中启用 brotli 并关闭 gzip 干扰
brotli on 必须写在 http 块顶层，且要显式关掉 gzip，否则浏览器可能随机选一种编码，无法稳定返回 br：
-
brotli on和gzip off必须成对出现，放在http块开头最稳妥 -
brotli_static on只查同名.br文件，不生成也不降级；若要动态压缩（如 API JSON），必须设brotli_static off并在对应location块里再写一遍brotli on -
brotli_comp_level别统一设 11：静态资源可用 8–11，打包 JS/CSS 推荐 6，动态 HTML/JSON 严格限 1–4 -
brotli_min_length建议设为1024（1KB），避免对小响应频繁触发压缩消耗 CPU
精准设置 brotli_types 避免无效压缩
乱加 brotli_types 是 CPU 升高的常见原因。Brotli 对已压缩格式（如 image/png、font/woff2、application/pdf）基本无效，还白耗资源：
- 只保留真正可压的类型：
text/html、text/css、application/javascript、application/json、image/svg+xml - 用
application/javascript替代过时的text/javascript，否则 Chrome 可能忽略 - 建议按目录精细控制，例如：
location ~ \.js$ { brotli on; brotli_types application/javascript; brotli_comp_level 6; } - 图片、字体、PDF 等二进制类型一律剔除，
location /images/ { brotli off; }是合理做法
预压缩 .br 文件权限与构建集成
brotli_static on 不会帮你生成 .br，它只检查文件是否存在——没文件就跳过，不压缩也不报错：
- Vite 项目配
vite-plugin-compression，Webpack 用compression-webpack-plugin，参数必须指定algorithm: 'brotliCompress' -
.br文件权限需为 Nginx worker 进程可读：常见坑是属主不是www-data或nginx，权限644不够时试试755 - CDN 或反向代理（如 Cloudflare）可能覆盖或解压响应头，测试时先直连 Nginx，用
curl -H "Accept-Encoding: br" -I https://yoursite.com/app.js看是否返回Content-Encoding: br
最容易被忽略的是：Brotli 只在 HTTPS 下被现代浏览器主动声明支持，HTTP 请求头里根本不会带 br；另外，PHP 的 zlib.output_compression=On 或 FastCGI 已输出 Content-Encoding，会直接阻止 Nginx 再次压缩。
