只要nginx版本≥1.9.11、编译启用--with-compat且模块支持动态编译,即可通过.so文件和load_module加载;需用同版本源码、替换--add-module为--add-dynamic-module后make modules生成.so,再复制至modules目录并配置load_module,最后nginx -t验证、-s reload生效。

只要 Nginx 版本 ≥ 1.9.11、编译时启用了 --with-compat,且第三方模块本身支持动态编译,就能在不重编译 Nginx 二进制的前提下,通过 .so 文件 + load_module 方式加载。
确认基础支持是否到位
先执行 nginx -V,检查三件事:
- 输出中 nginx version: 后的版本号是否 ≥ 1.9.11
- configure arguments: 行里是否包含 --with-compat
- 同一行是否出现 dynamic 或 --add-dynamic-module(表示构建环境支持动态模块)
再查你要加的模块文档(如 ngx_http_geoip2_module、nginx-rtmp-module),确认它明确声明支持 --add-dynamic-module 编译方式。
用源码编译生成 .so 动态模块文件
必须使用与当前运行 Nginx 完全一致的源码版本(例如线上是 1.24.0,就得下 nginx-1.24.0.tar.gz):
- 进入 Nginx 源码目录,复用原 configure 参数(可用
nginx -V提取),把--add-module=替换为--add-dynamic-module=/path/to/your/module - 执行
./configure --add-dynamic-module=/your/module/path,确保无报错 - 运行
make modules(不是make install),成功后会在objs/下生成.so文件,例如ngx_http_vts_module.so
部署并启用模块
生成的 .so 文件需放到 Nginx 的 modules 目录,并在主配置中声明:
- 用
nginx -V 2>&1 | grep modules-path查准路径(常见为/usr/lib64/nginx/modules或/usr/lib/nginx/modules) - 将
.so文件复制过去:sudo cp objs/xxx.so /usr/lib/nginx/modules/ - 设为可读:
sudo chmod 644 /usr/lib/nginx/modules/xxx.so - 编辑
/etc/nginx/nginx.conf,在最顶部(events { }前、任何块外)添加:load_module /usr/lib/nginx/modules/xxx.so;(推荐绝对路径)
验证与生效
改完配置不能直接重启:
- 先运行
nginx -t:提示 configuration file ... test is successful 表示语法正确 - 再执行
nginx -s reload,仅重载配置,worker 进程持续服务 - 查看错误日志:
tail -f /var/log/nginx/error.log,无 not binary compatible 或 undefined symbol 即为成功 - 功能测试:在
http或server块中使用该模块提供的指令(如geoip2、more_set_headers),发起请求验证是否真正生效











