Linux Nginx Brotli 压缩配置模板与核心避坑指南-Nginx-PHP中文网

nginx启用brotli必须先编译集成ngx_brotli模块，否则配置无效；需用nginx -v验证with-http_brotli_module，再在http块中配置brotli on、brotli_static on及精准types，并配合前端预生成.br文件。

linux nginx brotli 压缩配置模板与核心避坑指南

要在 Linux 上让 Nginx 真正用上 Brotli 压缩，不是加几行配置就完事——核心前提是模块必须编译进内核，否则所有指令都会报 unknown directive 或静默失效。

确认 ngx_brotli 模块已集成

这是第一步，也是最容易被跳过的致命环节。官方源（Ubuntu/Debian/CentOS Stream）的 apt/yum 包均不含该模块，必须手动编译或使用可信构建版（如 OpenResty 特定分支、Cloudflare Nginx）。

执行 nginx -V 2>&1 | grep with-http_brotli_module，有输出才表示成功编译进内核
若无输出，brotli on 配置会直接导致 nginx -t 报错
自编译时需确保：./configure --add-module=/path/to/ngx_brotli + 已安装 libbrotli-dev（Debian/Ubuntu）或 brotli-devel（RHEL/CentOS）

最小可用配置模板（放于 http{} 块）

以下为兼顾安全性、兼容性与效果的生产推荐配置，不依赖动态压缩，优先走预压缩路径：

Obsidian (Linux)

操作 Obsidian 库（纯 Markdown 笔记），并通过 notesmd-cli 实现自动化。

下载

brotli on;
brotli_static on;  # 启用 .br 文件查找，非 always
brotli_comp_level 6;
brotli_min_length 512;
brotli_types text/plain text/css text/javascript application/javascript application/json application/xml+rss text/html image/svg+xml;

brotli_static on 是关键：只在客户端声明支持 br（即请求头含 Accept-Encoding: br）且存在对应 .br 文件时才返回，不匹配则自动 fallback 到未压缩或 gzip（若已配）
绝不要写 brotli_types *，否则会对图片、PDF 等二进制文件尝试压缩，反而增大体积、白耗 CPU
MIME 类型要精准：application/javascript 比 text/javascript 更符合现代标准（Chrome 已弃用后者）

前端构建必须生成 .br 文件

brotli_static on 不会帮你压缩，它只读文件。没生成 .br，就等于没开。

Vite 项目：用 vite-plugin-compression，设 algorithm: 'brotliCompress'
Vue CLI：升级到 compression-webpack-plugin@9+，配置 algorithm: 'brotliCompress'
生成后检查 dist/app.js.br 是否存在，且 Nginx worker 进程对其有读权限（常见静默失败原因）

保留 gzip 作为兼容兜底

Brotli 和 gzip 可共存，浏览器会按 Accept-Encoding 优先级自动选择。建议在相同作用域（如 http{}）中同时启用：

gzip on;
gzip_vary on;
gzip_min_length 512;
gzip_comp_level 6;
gzip_types text/plain text/css application/javascript application/json text/html image/svg+xml;