NGINX 1.9.11+支持动态模块，需主程序启用--with-dynamic-modules且版本兼容；通过nginx -V验证支持，编译时用--add-dynamic-module和make modules生成.so文件，配置中load_module加载并测试。

NGINX 自 1.9.11 版本起支持动态模块（Dynamic Modules），允许将部分功能以 .so 文件形式独立编译、加载，无需重新编译整个 NGINX。这显著提升了模块迭代、灰度发布和多环境适配的灵活性。关键前提是：主程序必须启用 --with-dynamic-modules（实际由构建系统自动处理），且模块源码兼容目标 NGINX 版本。

一、确认 NGINX 是否支持动态模块

运行以下命令检查：

nginx -V 2>&1 | grep -o "dynamic" —— 若输出 dynamic，说明已启用动态模块支持；
nginx -V 2>&1 | grep -o "with-http_.*_module" —— 查看哪些模块被编译为动态（通常带 =shared）；
ls /usr/lib/nginx/modules/ 或 find / -name "*.so" 2>/dev/null | grep nginx —— 检查系统中已存在的动态模块文件。

若 nginx -V 中无 dynamic 字样，说明当前 NGINX 是静态编译的，需重新编译主程序或更换官方预编译包（如 nginx.org 的 mainline 包默认支持）。

二、编译第三方动态模块（以 echo-module 为例）

以 echo-nginx-module 为例，步骤如下：

• 下载与当前 NGINX 版本匹配的源码（如 NGINX 1.24.0，则获取对应 nginx-1.24.0.tar.gz）并解压
• 克隆模块源码：git clone https://www.php.cn/link/f9358d6ae3e191c88d6610acb757d152.git
• 进入 NGINX 源码目录，执行配置（不安装，仅生成构建文件）：
  

  ./configure --prefix=/usr/share/nginx \<br>
      --modules-path=/usr/lib/nginx/modules \<br>
      --add-dynamic-module=../echo-nginx-module

• 执行 make modules（注意：不是 make && make install），成功后会在 objs/ 目录下生成 ngx_http_echo_module.so
• 将生成的 .so 文件复制到配置中指定的 modules-path（如 /usr/lib/nginx/modules/），并确保权限可读

三、在配置中加载与验证动态模块

编辑 /etc/nginx/nginx.conf，在 events 块之前 添加：

load_module /usr/lib/nginx/modules/ngx_http_echo_module.so;

然后在 server 块中测试功能：

location /hello {
  echo "Hello from dynamic module!";
}

执行 nginx -t 验证语法，再 nginx -s reload 加载。访问 /hello 应返回对应文本。若报错 “module not found” 或 “version mismatch”，常见原因包括：
– .so 文件路径错误或权限不足
– 模块编译时所用 NGINX 源码版本与运行时 NGINX 版本不一致
– 模块依赖其他未加载的动态模块（如某些模块需先加载 ngx_http_lua_module.so）

四、安全分发与生产部署建议

• 将动态模块打包为独立 RPM/DEB 包（如使用 fpm 工具），与主程序解耦，便于版本追踪和回滚
• 模块文件建议存放在 /usr/lib/nginx/modules/（标准路径），避免硬编码绝对路径，改用变量如 $PREFIX/modules
• CI/CD 流程中，对每个模块构建任务绑定 NGINX 主版本号（如 nginx-1.24.0+echo-0.63），防止混用
• 上线前在 staging 环境执行 nginx -T | grep load_module 和 strace -e trace=openat nginx -t 2>&1 | grep so，确认模块真实加载