Nginx 安装时如何通过 add-module 动态编译安装第三方扩展模块

正确：--add-module是静态编译，必须重启服务；--add-dynamic-module才支持不中断加载动态模块.so文件。

不能通过 --add-module 实现“动态编译安装”——这个说法本身存在概念混淆。--add-module 是静态编译方式，会把模块代码直接编译进 nginx 主二进制文件，必须重启服务才能生效；而真正支持运行时不中断加载的，是 --add-dynamic-module，它生成独立的 .so 文件。

先确认你是否真的需要 --add-module

如果你的目标是：在已有 Nginx 运行环境中，不中断服务地新增功能（比如 headers-more、geoip2），那应该走动态模块路线，用 --add-dynamic-module，而不是 --add-module。

只有以下情况才适用 --add-module：

1. 全新安装 Nginx，且确定该第三方模块不支持动态编译（如部分老旧或自研模块）
2. 你接受停机：编译后需替换 nginx 二进制并执行 nginx -s stop && nginx
3. 你愿意承担配置回退风险：一旦新二进制出问题，得手动恢复旧版本

如果坚持用 --add-module 静态集成，操作要点如下

这适用于首次安装，或可接受服务中断的升级场景：

1. 进入 Nginx 源码目录（如 /usr/src/nginx-1.24.0）
2. 执行 nginx -V 查看原 configure 参数，**必须完整复用**，否则会丢失 SSL、gzip、realip 等基础能力
3. 在原有参数末尾追加 --add-module=/path/to/your/module，路径必须为绝对路径或相对于当前目录的有效路径
4. 运行 ./configure ... --add-module=...，确保无报错
5. 执行 make && make install（全新安装） 或 make && cp objs/nginx /usr/local/nginx/sbin/nginx（已安装环境替换二进制）
6. 重启服务：nginx -s stop && nginx（注意不是 reload）

更推荐的现代做法：用 --add-dynamic-module

只要 Nginx ≥ 1.9.11 且模块声明支持动态编译，就优先选这条路：

1. 同样进入源码目录，但用 --add-dynamic-module=/path/to/module 配置
2. 只运行 make modules（不是 make），生成 .so 文件
3. 将 .so 复制到 modules 目录（路径查 nginx -V | grep modules-path）
4. 在 nginx.conf 最开头添加 load_module modules/xxx.so;
5. 执行 nginx -t && nginx -s reload，worker 进程持续响应请求

常见踩坑提醒

无论哪种方式，都容易忽略这些关键点：

1. --add-module 和 --add-dynamic-module 不能混用在同一 configure 命令中
2. 多个模块要分别写多次 --add-module=xxx，不能合并或用通配符
3. 动态模块的 .so 文件需具备可读权限（chmod 644），且路径在 load_module 中必须是相对于 --modules-path 的相对路径
4. 若 nginx -V 输出中没有 --with-compat，说明当前 nginx 不支持动态模块，必须先用兼容模式重编译主程序