遇到 nginx 配置语法检查提示 unknown module，通常是因为编译 nginx 时未包含该模块对应的源码文件，或者动态加载的 .so 文件缺失。定位 missing 依赖的核心做法是：先通过 nginx -v 查看当前已编译的模块列表，确认静态模块是否缺失；若为动态模块，则需检查 load_module 指令指向的路径是否存在且权限正确。如果模块确实未在编译时加入，则需要重新编译 nginx 并添加相应的 --with- 或 --add-module 参数。
如何确认模块是否在编译时已包含
要确认某个模块（如 ngx_http_ssl_module）是否在当前 Nginx 二进制文件中存在，最直接的方法是运行 nginx -V 命令。该命令会输出 Nginx 的版本号、configure 脚本的参数以及已启用的模块列表。在输出的 configure arguments 中，查找以 --with- 开头的参数，这些代表静态编译的模块。例如，如果看到 --with-http_ssl_module，说明 SSL 模块已内置。如果列表中找不到对应模块，且你使用的是静态编译版本，那么该模块就是 missing 的，必须重新编译。
#!/bin/bash
# 1. 获取当前 Nginx 的 configure 参数
CONFIG_ARGS=$(nginx -V 2>&1 | grep -o 'configure arguments:.*' | sed 's/configure arguments: //')
# 2. 定义要检查的模块名（例如 http_ssl_module）
MODULE_NAME="http_ssl_module"
# 3. 检查模块是否在 configure 参数中
if echo "$CONFIG_ARGS" | grep -q "--with-${MODULE_NAME}"; then
echo "Module ${MODULE_NAME} is statically compiled."
elif echo "$CONFIG_ARGS" | grep -q "--with-${MODULE_NAME}=dynamic"; then
echo "Module ${MODULE_NAME} is dynamically compiled. Check load_module path."
else
echo "Module ${MODULE_NAME} is MISSING from compilation."
fi
# 4. 如果是动态模块，检查 .so 文件是否存在
if [ -f "/etc/nginx/modules/${MODULE_NAME}.so" ]; then
echo "Dynamic module file exists."
else
echo "Dynamic module file NOT found at /etc/nginx/modules/"
fi
上述脚本首先提取 nginx -V 的输出，判断模块是静态还是动态。对于动态模块，它进一步检查常见的模块目录 /etc/nginx/modules/ 下是否有对应的 .so 文件。如果脚本输出 MISSING，则说明需要重新编译或安装缺失的动态模块包。
如何修复缺失的静态模块依赖
当确认模块是通过静态编译缺失时，唯一的解决方案是重新编译 Nginx 源代码。你需要下载与当前运行版本一致的 Nginx 源码，解压后进入目录，运行 ./configure 命令。关键在于，你必须将之前使用的 configure 参数完整保留，并在其中添加缺失的模块参数。例如，如果缺少 http_ssl_module，需要在原有参数基础上追加 --with-http_ssl_module。完成配置后，执行 make 生成新的二进制文件，然后使用 make install 进行覆盖安装（注意备份配置文件）。
# 假设之前的 configure 参数如下： # ./configure --prefix=/etc/nginx --sbin-path=/usr/sbin/nginx ... # 1. 备份当前 nginx 二进制文件 cp /usr/sbin/nginx /usr/sbin/nginx.bak # 2. 进入源码目录 make # 3. 仅替换二进制文件，不覆盖配置文件 make install # 4. 验证模块是否已加载 nginx -V | grep http_ssl_module
这段代码展示了重新编译的标准流程。首先备份现有的 nginx 二进制文件以防万一，然后在源码目录下执行 make。这里的关键点是只运行 make 而不运行 make clean，以确保只编译必要的部分。最后通过 make install 更新二进制文件，并使用 nginx -V 验证新模块是否出现在配置参数中。此方法适用于所有静态模块的缺失问题。
动态模块加载失败时的路径排查
如果模块被标记为动态编译（即 configure 参数中包含 =dynamic），但 nginx -t 仍报错 unknown module，问题通常出在 load_module 指令指定的路径上。Nginx 主配置文件 nginx.conf 顶部会有类似 load_module modules/ngx_http_ssl_module.so; 的指令。你需要确认该路径相对于 -p 前缀目录是否正确，以及 .so 文件是否具有可执行权限。此外，动态模块可能依赖于其他系统库（如 OpenSSL），如果系统库版本不匹配或缺失，也会导致模块加载失败，此时应使用 ldd 命令检查 .so 文件的依赖项。
