排查nginx load_module动态模块版本不匹配故障，核心是确认模块编译时的nginx主版本号（如1021000）、abi及符号与当前运行nginx严格一致；否则将出现undefined symbol、version mismatch或段错误。
排查 Nginx load_module 加载动态模块时的版本不匹配故障，核心是确认模块编译时所依赖的 Nginx 版本、ABI（应用二进制接口）与当前运行的 Nginx 是否一致。版本不匹配通常表现为启动失败、报错如 undefined symbol、Version mismatch 或直接段错误（Segmentation fault）。
检查 Nginx 主版本与 ABI 兼容性
Nginx 动态模块要求：模块编译时的 nginx_version（主版本号，如 1021000 表示 1.21.0）和 NGINX_VERSION 字符串必须与当前 Nginx 二进制完全一致；ABI 级别（由 ngx_cycle_t 等核心结构体布局决定）也需兼容。Nginx 官方明确说明：动态模块仅保证与**同主版本号**（如 1.20.x、1.21.x）的 Nginx 兼容，跨主版本（如 1.20 → 1.21）即使小版本接近也大概率失败。
- 运行
nginx -v查看当前 Nginx 版本（如nginx version: nginx/1.21.6） - 查看模块源码或构建日志中的
nginx_version宏值，或用strings your_module.so | grep -E "(nginx|version|0x[0-9a-f]{6,})"粗略提取 - 若模块来自第三方（如
nginx-module-vts），务必下载对应 Nginx 版本的预编译包，或用相同源码树重新编译
验证模块符号与 Nginx 符号是否匹配
版本不匹配常体现为符号缺失，尤其是 ngx_http_module、ngx_core_module 等核心模块的函数或变量地址解析失败。
- 用
nm -D /path/to/your_module.so | grep ngx_查看模块导出的关键符号 - 用
nm -D $(which nginx) | grep "T ngx_"查看 Nginx 二进制导出的符号（注意加-D只看动态符号） - 对比关键函数如
ngx_http_add_location、ngx_conf_set_str_slot是否在两边都存在且类型一致（T表示定义，U表示未定义） - 若模块中大量符号显示为
U，而 Nginx 中无对应T，说明 ABI 已断裂，需重编译模块
启用调试日志并捕获加载过程
Nginx 在加载模块时会输出关键信息，但默认级别不显示细节。可通过临时提升日志级别定位失败点。
- 在
nginx.conf的main上下文中添加：
error_log /var/log/nginx/error.log debug; - 执行
nginx -t测试配置，观察日志中是否出现类似：loading module "/path/to/ngx_http_geoip2_module.so"<br>module: 000055AABBCCDD00 "ngx_http_geoip2_module" (compatibility version 0.0.0)
- 若加载后立即报
undefined symbol: ngx_http_upstream_init_round_robin类错误，说明模块引用了当前 Nginx 未导出或签名不同的函数 - 测试完及时改回
error_log ... warn;，避免日志爆炸
重建模块：确保工具链与目标 Nginx 严格一致
最可靠的方式是用目标 Nginx 源码树重新编译模块，而非通用 SDK 或旧构建环境。
- 下载与运行中 Nginx **完全相同版本**的源码（如
nginx-1.21.6.tar.gz） - 解压后进入目录，执行：
./configure --with-compat --add-dynamic-module=/path/to/your/module<br>make modules
生成的objs/xxx.so即为兼容模块 - 注意：不要使用系统包管理器安装的
nginx-devel（如 CentOS 的 rpm），它可能对应不同 patch 版本；以实际nginx -V输出的 configure arguments 为准 - 若模块含 C++ 代码，还需确保 GCC 版本、
libstdc++ABI 一致（可查readelf -V your_module.so | grep -A5 -B5 "GLIBCXX"）
