必须先动态编译集成ngx_brotli模块，再通过USR2/WINCH/QUIT信号完成Nginx二进制平滑升级，确保零停机；配置需在http块显式启用brotli on、设置comp_level与types，并关闭gzip冲突，最后用curl验证Content-Encoding: br。
要在生产环境安全启用 Brotli 并保持服务连续性，必须分两步走：先动态编译集成 ngx_brotli 模块，再用平滑升级方式替换 Nginx 二进制。这两步不能合并操作，否则会导致模块加载失败或连接中断。
动态编译 ngx_brotli 模块（不重装 Nginx）
动态模块方案允许在保留原 Nginx 主程序的前提下，仅加载新模块，适合已稳定运行的线上环境。
- 先安装 libbrotli 库：克隆 google/brotli 仓库，执行
./configure --prefix=/usr/local && make && sudo make install，随后运行sudo ldconfig刷新系统库缓存 - 拉取 google/ngx_brotli 模块源码，注意使用与当前 Nginx 版本兼容的分支（如 Nginx 1.24.x 对应 ngx_brotli 的 master 分支）
- 进入 Nginx 源码目录，用
nginx -V输出中的原始 configure 参数，追加--add-dynamic-module=/path/to/ngx_brotli --with-compat，然后make（不要make install） - 将生成的
objs/ngx_http_brotli_filter_module.so复制到 Nginx 模块目录（如/usr/local/nginx/modules/），并在nginx.conf开头添加load_module modules/ngx_http_brotli_filter_module.so;
Nginx 二进制平滑升级（零停机切换）
当新版本 Nginx 已包含 Brotli 支持，或需同步升级内核、OpenSSL 等底层组件时，必须通过信号机制完成热切换，避免 kill -9 或 systemctl restart 导致连接断开。
- 备份当前二进制：
cp /usr/local/nginx/sbin/nginx /usr/local/nginx/sbin/nginx.old - 用与旧版完全一致的 configure 参数编译新版 Nginx，确保
--prefix、--modules-path、启用模块等全部对齐；新二进制位于objs/nginx - 覆盖旧文件：
cp objs/nginx /usr/local/nginx/sbin/nginx，并验证权限与属主一致 - 发送
USR2信号启动新 master：kill -USR2 $(cat /usr/local/nginx/logs/nginx.pid)，此时出现nginx.pid.oldbin，新旧 master 共存 - 发送
WINCH给旧 master：kill -WINCH $(cat /usr/local/nginx/logs/nginx.pid.oldbin)，旧 worker 逐步退出，不再接受新请求 - 确认旧 worker 进程消失后，发送
QUIT终止旧 master：kill -QUIT $(cat /usr/local/nginx/logs/nginx.pid.oldbin)
Brotli 配置生效与验证要点
模块加载成功 ≠ 压缩生效。配置错误、类型遗漏或 gzip 冲突都会导致 br 不触发。
- 在
http块中启用：必须显式写brotli on;，不能只靠load_module - 设置压缩等级和类型：
brotli_comp_level 6;和brotli_types text/css application/javascript text/html;要覆盖实际返回的 MIME 类型 - 禁用 gzip 冲突：若同时开启 gzip，浏览器可能优先选 gzip；建议关闭
gzip on;或确保gzip_disable "msie6";等规则不误判 - 验证响应头：用
curl -H "Accept-Encoding: br" -I https://yoursite.com/app.js查看是否返回Content-Encoding: br，且状态码为 200
回滚与异常处理策略
上线后发现异常（如 500 错误、worker 崩溃），需立即回退，无需重新编译。
- 若新 master 尚未完全接管，直接向新 master 发送
QUIT，旧 master 会自动恢复监听 - 若已终止旧 master，但新版本异常，可复制备份的
nginx.old覆盖当前二进制，再发HUP重载配置 - 检查日志重点项：
error.log中是否有module “ngx_http_brotli_filter_module.so” is not binary compatible（说明 configure 参数不一致）或dlopen() failed（libbrotli 路径或版本问题） - 所有操作前务必执行
nginx -t，升级后立刻用ps aux | grep nginx确认进程结构符合预期
