Nginx 中 Brotli 压缩如何排查因模块未正确加载导致的压缩失效故障

关键不是看配置写了没，而是验证模块是否真被Nginx识别、加载并参与请求处理链；需依次执行nginx -V | grep ngx_brotli确认编译集成、nginx -t检查指令识别、load_module路径与权限校验、指令位置及拼写排查，并最终用curl -H "Accept-Encoding: br" -I验证响应头Content-Encoding: br。

排查 Brotli 压缩失效是否由模块未正确加载引起，关键不是看配置写了没，而是验证模块是否真被 Nginx 识别、加载并参与请求处理链。很多“brotli on;”配置看似完整，但模块根本没进内存，压缩自然不会发生。

确认 Nginx 启动时是否加载了 ngx_brotli 模块

模块未加载是压缩失效最直接的原因。不能只依赖配置存在，必须查运行态：

1. 执行 nginx -V 2>&1 | grep -o ngx_brotli —— 若无输出，说明 configure 阶段就没引入模块，编译时已排除
2. 若输出有 ngx_brotli，再检查实际进程是否加载：运行 nginx -t，观察是否有 “unknown directive ‘brotli’” 报错；有则代表模块虽编译进去了，但运行时未启用（如动态模块路径错误或 load_module 指令缺失）
3. 对动态模块（.so），确认 load_module modules/ngx_http_brotli_filter_module.so; 出现在配置的 http 块顶部，且 .so 文件真实存在、权限可读、架构匹配（如 x86_64）

验证 brotli 指令是否被识别且无语法错误

即使模块加载成功，指令位置或上下文错误也会让配置静默失效：

1. brotli 相关指令（如 brotli on;、brotli_comp_level 4;）必须放在 http、server 或 location 块内，不能出现在 if、map 或 event 块中
2. 检查是否有拼写错误：比如写成 brotil on; 或 brotli_enable on;，Nginx 不报错但忽略
3. 运行 nginx -t 后，留意 warning 级提示，例如 “directive is not terminated by semicolon”，这类问题常导致后续 brotli 指令整体不生效

检查响应头是否真正携带 Content-Encoding: br

这是最终验证环节，绕过所有中间判断，直击结果：

1. 用 curl 发起明确支持 Brotli 的请求：curl -H "Accept-Encoding: br" -I https://your-domain.com/test.js，查看响应头中是否有 Content-Encoding: br
2. 对比同一请求去掉 Accept-Encoding 头的结果，确认差异仅在编码头，而非状态码或 body 变化
3. 若始终返回 Content-Encoding: gzip 或无该头，且已确认 gzip 和 brotli 同时开启，则大概率是模块未参与协商流程——常见于模块加载顺序错误（如 brotli filter 被其他 filter 覆盖）、或配置被更高优先级 location 覆盖

排除模块与 Nginx 版本 ABI 不兼容

升级 Nginx 后出现压缩失效，很可能是模块二进制不匹配：

1. 运行 nginx -v 查版本（如 1.25.3），再查该版本下 ngx_brotli 最新 README 是否声明支持；不支持时模块可能加载成功但函数调用失败，指令被跳过
2. 检查 error.log 中是否有 module version mismatch、undefined symbol ngx_http_brotli_filter 类报错，这是 ABI 断裂的典型标志
3. 稳妥做法：用当前 Nginx 源码重新编译 ngx_brotli，生成新 .so 替换旧文件，再 reload