Nginx 编译添加第三方模块需版本匹配、复用原 configure 参数并正确指定路径；支持静态集成（--add-module）或动态模块（--add-dynamic-module + --with-compat），后者无需重装主程序。
Nginx 源码编译添加第三方模块，本质是把外部模块代码“嵌入”到 Nginx 构建流程中，生成带新功能的可执行文件或动态模块。它不支持运行时安装，必须重新编译。关键在于版本匹配、参数复用和路径正确。
确认当前 Nginx 环境与模块兼容性
执行 nginx -V（注意是大写 V），重点看两行：
-
nginx version:后的版本号（如 1.24.0）→ 必须下载完全一致的源码包 -
configure arguments:后的整串参数 → 后续重编译必须完整复用，否则会丢失 SSL、HTTP/2、gzip 等已有功能
检查目标模块文档，确认它支持该 Nginx 版本范围，并留意是否依赖额外库（如 libbrotli-dev、pcre2、zlib-ng）或要求启用特定内置模块（如 --with-http_realip_module）。
下载并准备源码与模块目录
- 从 nginx.org/download 下载对应版本源码，例如：
wget https://www.php.cn/link/47c4c6f12cb08bc39560a6681f15997d/nginx-1.24.0.tar.gz tar -zxvf nginx-1.24.0.tar.gz
- 将第三方模块（如
ngx_brotli、headers-more-nginx-module）克隆或解压到独立目录，例如：mkdir -p /usr/src/nginx-modules git clone https://github.com/google/ngx_brotli.git /usr/src/nginx-modules/ngx_brotli
- 进入模块目录，运行
git submodule update --init（若模块含子模块，如 Brotli 需要brotli库）。
配置并编译安装
进入 Nginx 源码目录（如 /usr/src/nginx-1.24.0），执行原 configure 命令，并在末尾追加 --add-module= 参数：
./configure \ --prefix=/etc/nginx \ --sbin-path=/usr/sbin/nginx \ --modules-path=/usr/lib64/nginx/modules \ --conf-path=/etc/nginx/nginx.conf \ --error-log-path=/var/log/nginx/error.log \ --http-log-path=/var/log/nginx/access.log \ --pid-path=/var/run/nginx.pid \ --with-http_ssl_module \ --with-http_v2_module \ --with-http_realip_module \ --add-module=/usr/src/nginx-modules/ngx_brotli \ --add-module=/usr/src/nginx-modules/headers-more-nginx-module
- 多个模块用多个
--add-module=，顺序无关 - 若想生成
.so动态模块（非静态集成），需加--with-compat并用--add-dynamic-module=替代--add-module=，最后在nginx.conf开头加load_module modules/ngx_http_brotli_filter_module.so;
完成 configure 后：
make && make install
验证：nginx -t 检查配置语法，nginx -V 确认新模块已出现在输出中（部分模块会显示在 configure arguments 或新增指令说明里）。
动态模块方式（推荐用于生产环境升级）
满足条件：Nginx ≥ 1.9.11，且编译时带 --with-compat
- 不修改主程序，只编译
.so文件 - 步骤简化为：
./configure --add-dynamic-module=... && make modules - 将生成的
.so复制到modules_path指定目录 - 在
nginx.conf第一行添加load_module modules/xxx.so; -
nginx -t && nginx -s reload即可生效
不复杂但容易忽略
