Brotli模块排查需分三类：未编译、配置错误、运行崩溃；先用nginx -V和nm验证是否编译，再检查配置语法与上下文，最后通过响应头和错误日志确认生效或崩溃原因。
排查 Brotli 模块加载失败或语法报错，关键在于分清“模块没编译进去”“配置写错导致指令无效”“模块加载了但运行崩溃”这三类问题。Brotli 不是 Nginx 官方内置模块，宝塔等面板默认也不带，所以不能只看配置有没有写，必须逐层验证。
确认 Brotli 模块是否真被编译进 Nginx
很多故障根源其实是二进制里压根没有 Brotli 支持，配置再对也白搭。
- 运行 nginx -V 2>&1 | grep -i brotli，若无任何输出，说明未编译；常见于宝塔默认安装、直接 yum/apt 安装的包
- 若看到 --add-module=../ngx_brotli 或 --with-compat（动态模块必需），再查符号：nm -D $(which nginx) | grep -i brotli_filter，有输出才表示静态链接成功
- 如果是动态模块（.so 文件），执行 ls -l /path/to/ngx_http_brotli_filter_module.so 确认文件存在，并检查 nginx.conf 中 load_module 路径是否与 prefix 相对路径一致（如 modules/ngx_http_brotli_filter_module.so）
检查 Brotli 相关配置语法是否合法
拼写错误、上下文错位、与 gzip 冲突都会让指令静默失效，不报错但也不起作用。
- 确保只启用一种压缩：Brotli 和 gzip 不能同时对同一 location 生效，否则可能触发 ERR_CONTENT_DECODING_FAILED；建议注释掉 gzip on;，只留 brotli on;
- 高频拼写错误：brotli_types 写成 brotly_types、brotli_comp_level 漏掉下划线、brotli_static 误为 brotli_statuc
- 指令位置必须合法：brotli on; 只能在 http 或 server 块中，不能放在 location 里；brotli_types 同理，放错位置会提示 unknown directive
验证 Brotli 是否真正生效
语法正确 ≠ 实际压缩。必须通过响应头和日志交叉判断。
- 在对应 server 或 location 中加：add_header X-Brotli-Status $brotli_ratio;（若支持）或更通用的 add_header X-Content-Encoding $sent_http_content_encoding;
- 用 curl -I https://yoursite.com/test.js 查看响应头，确认含 Content-Encoding: br 且响应体为二进制（非明文）
- 若始终返回 Content-Encoding: gzip 或无该头，说明 Brotli 未命中：检查 brotli_types 是否包含 application/javascript，或文件后缀是否匹配
定位加载后崩溃或 worker 退出
模块编译环境不一致、OpenSSL 版本冲突、与其它第三方模块（如 echo、lua）钩子覆盖，都可能导致启动后 worker 随机退出。
- 临时注释所有 load_module，只保留 Brotli，再 nginx -t && nginx -s reload，观察是否还崩溃
- 查看错误日志：tail -n 30 /var/log/nginx/error.log，搜索 segmentation fault、undefined symbol: ngx_http_brotli、relocation error
- 用 strace -e trace=openat,open nginx -t 2>&1 | grep brotli 确认 .so 文件是否被实际加载，以及加载顺序是否在核心模块之后
