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，确认模块真实加载
