在 linux 中检查 nginx 模块之间的依赖冲突，最直接的方法是查看编译时的配置日志或使用 -v 参数获取已安装版本的详细列表，并结合 ldd 命令分析动态链接库的符号依赖。如果 nginx 启动失败或加载模块时报错，通常是因为某个模块依赖的动态库版本不匹配、缺失，或者两个模块导出了相同的静态变量导致冲突。通过 nginx -t 测试配置文件可以初步发现语法错误，但深层的符号冲突需要借助系统级的依赖检查工具来定位。
如何查看当前 Nginx 已加载的模块列表
要确认当前运行的 Nginx 包含了哪些模块，可以使用 nginx -V 命令。这个命令会输出 Nginx 的版本信息以及编译时使用的 configure 参数。在输出的 --with- 和 --add-module= 等参数中，你可以看到所有内置模块和第三方模块的名称。例如，如果你安装了 ngx_http_lua_module，它通常会出现在列表中。需要注意的是，nginx -V 只能显示编译时确定的模块，无法直接显示运行时动态加载的模块（如果支持的话），但对于大多数标准部署，这足以识别潜在的冲突源。
nginx -V 2>&1 | grep -oP '(?<=--with-)[^ ]+|(?<=--add-module=)[^ ]+'
上述命令会从 nginx -V 的输出中提取所有以 --with- 或 --add-module= 开头的模块名。假设输出中包含 --with-http_ssl_module 和 --add-module=/path/to/ngx_http_lua_module，这表明 Nginx 编译时启用了 SSL 支持和 Lua 模块。接下来，你需要检查这些模块之间是否存在已知的依赖关系。例如，ngx_http_lua_module 依赖于 libluajit-5.1，而 http_ssl_module 依赖于 openssl。如果系统中缺少这些库，Nginx 将无法启动。
如何使用 ldd 检查模块的动态库依赖
当 Nginx 启动报错如 error while loading shared libraries: libxxx.so.x 时，说明某个模块依赖的动态库缺失或版本不对。使用 ldd 命令可以列出 Nginx 二进制文件及其所有动态库的依赖关系。首先，找到 Nginx 的二进制文件路径，通常是 /usr/sbin/nginx 或 /usr/local/nginx/sbin/nginx。然后运行 ldd /path/to/nginx，输出将显示所有依赖的共享库及其状态。如果某个库显示为 not found，则说明该库未安装在系统中，或者路径不在 LD_LIBRARY_PATH 中。
ldd /usr/sbin/nginx | grep -i 'not found'
执行上述命令后，如果输出为空，说明所有依赖库都已找到。如果有输出，例如 libluajit-5.1.so.1 => not found，则表明 ngx_http_lua_module 所需的 LuaJIT 库缺失。此时，你需要安装相应的开发包，如 apt-get install libluajit-5.1-dev（Debian/Ubuntu）或 yum install lua-JIT-devel（CentOS/RHEL）。安装后，可能需要重新编译 Nginx 或更新 ldconfig 缓存。此外，如果两个模块依赖不同版本的同一库（如 libpcre），也可能导致冲突，这时需要确保所有模块都兼容同一个库版本，或者使用静态编译方式避免动态库冲突。
基于 nginx -t 返回的具体错误排查模块冲突
在使用 nginx -t 测试配置文件时，如果模块之间存在严重的依赖冲突，Nginx 可能会直接拒绝加载并抛出错误。例如，如果两个模块试图绑定同一个端口或监听相同的地址，nginx -t 会报告 bind() to 0.0.0.0:80 failed (98: Address already in use)。这种冲突是配置层面的，而非库依赖层面。另一种情况是，如果某个模块初始化失败，nginx -t 可能会显示 module initialization failed。为了复现这种情况，我们可以创建一个简单的测试场景：假设我们有一个自定义模块 ngx_test_module，它在初始化时尝试访问一个不存在的资源，导致启动失败。
#include <ngx_config.h>
#include <ngx_core.h>
static ngx_int_t ngx_test_module_init(ngx_conf_t *cf) {
// 模拟一个会导致初始化的错误
return NGX_ERROR;
}
static ngx_command_t ngx_test_module_commands[] = {
{ ngx_string("test_directive"),
NGX_MAIN_CONF|NGX_DIRECT_CONF|NGX_CONF_NOARGS,
ngx_test_module_init,
0, 0, NULL },
ngx_null_command
};
static ngx_module_t ngx_test_module = {
NGX_MODULE_V1,
&ngx_test_module_ctx,
ngx_test_module_commands,
NGX_CORE_MODULE,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
NGX_MODULE_V1_PADDING
};
将上述代码编译进 Nginx 后，运行 nginx -t 将会得到类似 nginx: [emerg] module "ngx_test_module" initialization failed 的错误。这表明 ngx_test_module 在初始化阶段失败了，可能是由于内部逻辑错误或依赖的资源不可用。在这种情况下，你需要检查模块的代码逻辑，确保它正确初始化了所有必要的资源。如果多个模块同时失败，nginx -t 会按顺序报告错误，你可以根据错误信息逐一排查。此外，如果模块之间存在全局变量冲突，例如两个模块都定义了同名的全局变量，编译器可能会报错，或者在运行时导致未定义行为。为了避免这种情况，建议使用命名空间或前缀来区分不同模块的全局变量。
