当前位置：首页 > 文章列表 > 文章 > linux > Nginx开启Brotli压缩方法详解

Nginx开启Brotli压缩方法详解

2026-05-23 16:21:45 0浏览收藏

Nginx原生不支持Brotli压缩，必须手动编译集成ngx_brotli模块并严格配置才能真正生效——仅克隆源码或宝塔中误选“一键安装”而未勾选“编译安装”会导致brotli指令被忽略；验证需通过`nginx -V | grep with-http_brotli_module`确认模块已嵌入，并用`curl -H "Accept-Encoding: br" -I`测试HTTPS响应头是否返回`Content-Encoding: br`；配置时务必在http块顶层启用`brotli on`、显式关闭gzip以防冲突、合理设置`brotli_static on`配合构建工具（如Vite/webpack）预生成`.br`文件，同时避开CDN干扰、调优压缩等级（推荐4–6）与最小长度（建议≥1024），否则极易陷入“看似开启实则无效”的常见陷阱。

Nginx怎么开启Brotli压缩 Nginx网页压缩算法二次优化详解

直接说结论：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 { ...
brotli on;
brotli_comp_level 6;
brotli_types text/plain text/css application/javascript application/json text/xml image/svg+xml;
brotli_static on;
gzip off;  # 关键：不关掉 gzip，浏览器可能随机选 gzip 或 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'
import react from '@vitejs/plugin-react'
import { compression } from 'vite-plugin-compression2'

export default defineConfig({
  plugins: [
    react(),
    compression({
      algorithm: 'brotliCompress',
      ext: '.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 这条指令，很多人复制配置时漏掉，结果白配了。

到这里，我们也就讲完了《Nginx开启Brotli压缩方法详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于Linux的知识点！

Linux