启用 Nginx Brotli 模块失败主因是依赖缺失、路径错误或编译环境不匹配；先用 nginx -V | grep -i brotli 验证是否编译进二进制，再查 ldd module.so | grep brotli 确认 libbrotli 运行库存在，最后通过 curl -H "Accept-Encoding: br" 检查响应头是否含 Content-Encoding: br。
启用 Nginx Brotli 模块时出错，90% 是依赖没装全、路径没对上，或编译环境不匹配。不是模块本身有问题，而是它对底层库版本和编译链特别敏感。
确认 Brotli 模块是否真被加载
先别急着重编译，用最直接的方式验证模块是否存在：
- 运行 nginx -V 2>&1 | grep -i brotli，看到
with-http_brotli_filter_module才算成功编译进去了 - 如果输出为空，说明模块根本没参与编译；若报
unknown directive "brotli"，说明模块加载失败或配置语法错误 - 检查 error.log 启动日志，常见提示如
dlopen() "/path/to/ngx_http_brotli_filter_module.so" failed，指向动态链接问题
排查 libbrotli 运行时依赖缺失
Brotli 模块依赖系统级的 libbrotlienc.so 和 libbrotlidec.so，只装模块源码不够，必须有对应运行库：
- 执行 ldd /path/to/ngx_http_brotli_filter_module.so | grep brotli，看是否显示
not found - 用 find /usr -name "libbrotlienc.so*" 2>/dev/null 查找库文件位置，常见路径是
/usr/lib/x86_64-linux-gnu/（Debian/Ubuntu）或/usr/lib64/（RHEL/CentOS） - 若库存在但未被识别，把路径加到
/etc/ld.so.conf.d/brotli.conf，再运行 sudo ldconfig -v | grep brotli 确认生效 - 注意：仅安装
libbrotli1（运行库）可能不够，某些发行版需额外装libbrotli-dev或brotli-devel提供头文件用于编译
解决 configure 阶段编译报错
编译 Nginx 时加了 --add-module=../ngx_brotli 却报错，常见原因如下：
-
模块源码不完整：确保下载的是完整 git clone（含
config脚本），不是只下 release zip —— 缺config会导致no config file found - PCRE/OpenSSL/zlib 版本不兼容：Brotli 模块在 Nginx 1.25+ 中需 OpenSSL ≥ 1.1.1 且 PCRE2 推荐；若系统默认是 PCRE1，configure 可能静默失败
-
路径参数写错：比如
--with-openssl=/opt/openssl指向的是源码目录，但你装的是二进制包，则应改用--with-openssl-include=/opt/openssl/include --with-openssl-lib=/opt/openssl/lib -
权限或路径不可写：
--prefix指定的安装目录需当前用户有写权限，否则 configure 末尾会卡住或报错
验证启用后是否真正生效
配置写了 brotli on; 也不代表压缩真的起了作用：
- 用 curl -H "Accept-Encoding: br" -I http://your-site.com/test.js 查响应头，必须出现
Content-Encoding: br - 确保
brotli_static off;（动态压缩必须关掉静态模式），且brotli_types包含目标 MIME 类型，如text/css application/javascript - 排除 gzip 干扰：若同时开启
gzip on;，Nginx 默认按gzip优先协商，Brotli 不会触发——应禁用全局 gzip，或仅保留极窄兜底 - 检查客户端是否真实支持：Chrome/Firefox 新版支持，但 curl 默认不发
br，需显式加头；旧版 iOS Safari 不支持，会回落到无压缩
