Nginx启用Brotli需先编译加载ngx_brotli模块，再在http块中配置brotli on、comp_level、types等指令；必须验证模块注入（nginx -V）、响应头Content-Encoding: br及预压缩文件权限，同时保留gzip兜底以保障兼容性。
Brotli在Nginx中不是开个开关就能生效的——它必须先编译进Nginx，再配对启用，否则brotli on会直接报错“unknown directive”。
编译Nginx时必须显式加入ngx_brotli模块
官方Nginx不带Brotli支持，apt install nginx或brew install nginx装出来的默认都不行。你得自己编译：
- 先克隆
ngx_brotli仓库，并递归拉取其依赖的brotli子模块：git clone --recurse-submodules https://github.com/google/ngx_brotli - 进入
ngx_brotli/deps/brotli，用cmake构建静态库（注意加-DBUILD_SHARED_LIBS=OFF，否则Nginx加载时会找不到符号） - 回到Nginx源码目录，
./configure时必须带上--add-module=/path/to/ngx_brotli，缺了这句，后续所有配置都无效 -
make && make install后，用nginx -V 2>&1 | grep -o with-http_brotli_module确认是否成功注入
brotli_comp_level别无脑设11，要按资源类型分层
压缩级别不是越高越好，它直接影响CPU时间和首字节延迟（TTFB）。实测显示：
- 动态接口返回的HTML/JSON：用
brotli_comp_level 1–4，压缩耗时降低60%，压缩率仍比Gzip 9级高 - Vue/React打包产物（如
app-xxx.js）：推荐6，平衡压缩率（~65%）和响应速度 - 长期不变的静态资源（
logo.svg、reset.css）：可设8–11，配合brotli_static on预压缩 - 设成
11时，单次压缩可能多耗30ms，在QPS高的API网关上容易拖慢整体P95延迟
brotli_static on必须配合预生成.br文件，否则形同虚设
这个指令不会帮你实时压缩，它只做一件事：当客户端请求/main.js时，检查是否存在/main.js.br，有就直接发，没就跳过——不会 fallback 到动态压缩。
PigX UI 前端开发
下载
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
立即学习“前端免费学习笔记（深入）”；
- 前端构建阶段就要生成.br文件：比如Vite项目用
vite-plugin-compression，设置algorithm: 'brotliCompress' - Nginx配置里
brotli_types必须和实际生成的.br文件MIME类型严格一致，比如application/javascript不能写成text/javascript（后者Chrome已弃用） - 常见坑：
brotli_static on开启后，如果.br文件权限不对（如Nginx worker进程无法读），日志里只会静默忽略，不报错也不降级 - 验证是否命中：看响应头是否有
Content-Encoding: br，且Content-Length明显小于原始文件
兼容性兜底必须靠gzip，不能只信Accept-Encoding
哪怕现在98%的现代浏览器支持Brotli，仍有两类请求绕不开gzip：
- 企业内网某些老旧代理（如Blue Coat、Zscaler）会主动剥离
br，只留gzip在Accept-Encoding里 - curl/wget等工具默认不发
br，CI脚本或监控探测可能拿不到压缩响应 - 正确做法是同时开启
gzip on和brotli on，并确保gzip_types和brotli_types范围一致；Nginx会按Accept-Encoding优先级自动选最优算法 - 别依赖
brotli_static on+gzip_static on双开——它们互不感知，.br缺失时不会自动查.gz，得靠动态gzip兜底
最易被忽略的一点：Brotli的窗口大小（brotli_window）默认22MB，但如果你在容器里跑Nginx，cgroup内存限制低于这个值，worker进程可能OOM崩溃，此时得显式调小到512k或1m。这不是性能优化点，而是稳定性生死线。
