Nginx动态模块加载需满足版本≥1.9.11、编译含--with-compat、模块支持动态ABI三条件，通过load_module在main上下文声明，nginx -s reload生效，须用同源码同环境编译.so并放至--modules-path路径。
只要 Nginx 版本 ≥ 1.9.11、编译时启用了 --with-compat，且第三方模块本身支持动态 ABI，就能通过 load_module 加载 .so 文件——这不是热插拔，而是启动时加载、nginx -s reload 时生效。
确认基础支持是否到位
缺一不可，否则配置会静默失败或报错：
- 运行
nginx -v，确保版本号 ≥ 1.9.11 - 运行
nginx -V 2>&1 | grep -o with-compat，有输出才表示二进制支持动态模块 - 检查
nginx -V输出中的--modules-path（如/usr/lib/nginx/modules），这是推荐存放路径 - 查阅目标模块文档，确认它明确支持
--add-dynamic-module方式（例如ngx_http_geoip2_module、nginx-rtmp-module）
本地编译匹配的 .so 文件
不能直接用别人编译好的 .so，必须用与当前 Nginx 完全一致的源码和编译环境生成：
- 下载与运行中 Nginx 版本号完全相同的源码包（如正在用 1.24.0，就下 nginx-1.24.0.tar.gz）
- 进入该源码目录，执行：
./configure --with-compat --add-dynamic-module=/path/to/your/module - 执行
make modules（不是make或make install），成功后在objs/下生成类似ngx_http_echo_module.so的文件 - 将 .so 复制到
--modules-path目录，例如：cp objs/ngx_http_echo_module.so /usr/lib/nginx/modules/ - 设置可读权限：
chmod 644 /usr/lib/nginx/modules/ngx_http_echo_module.so
在配置中声明并启用
load_module 必须写在 nginx.conf 最顶层（main 上下文），即 events { } 之前、任何 http 或 server 块之外：
- 添加一行：
load_module modules/ngx_http_echo_module.so;
注意：路径是相对于--modules-path的相对路径；若写绝对路径，则必须以/开头，如load_module /usr/lib/nginx/modules/ngx_http_echo_module.so; - 保存后执行
nginx -t验证语法 - 验证通过后执行
nginx -s reload—— 此操作不中断服务，worker 进程持续处理请求 - 验证是否加载成功：
nginx -V 2>&1 | grep -i "built.*module"，或检查error.log中是否有模块初始化日志
常见失败原因与应对
多数问题集中在路径、权限或兼容性上：
-
nginx -t报 “module not found”：核对load_module路径是否准确，是否漏掉.so后缀，文件是否存在且可读 - 启动或 reload 后无效果：检查
error.log，常见错误如module is not binary compatible，说明模块未用同版本源码+相同编译参数构建 - 模块功能不生效：确认模块对应指令是否在正确上下文启用（如
brotli on必须放在http或server块内，而非load_module行附近） - 权限被忽略：worker 进程需有读取 .so 文件的权限，
chmod 644是安全起点
