应先运行nginx -v检查编译参数是否含目标模块，若缺失则需重新编译；再确认动态模块是否通过load_module正确加载且.so文件存在可读；最后用nginx -t定位报错指令，结合error.log中module not found等关键词验证运行时依赖与权限。
模块加载失败在 Nginx 中通常不直接报“模块没加载”，而是表现为 unknown directive、invalid number of arguments 或启动时静默退出。排查需紧扣“编译—配置—运行”三层逻辑，不能只盯着配置文件改。
确认模块是否真被编译进二进制
这是最容易跳过的一步，但决定后续所有操作是否有效。
- 运行
nginx -V（大写 V），查看完整编译参数；搜索--with-http_ssl_module、--add-module=等关键词，确认目标模块存在 - 若用第三方模块（如
ngx_http_geoip2_module），检查输出中是否有对应--add-module=/path/to/src - 若无相关参数，说明该模块未编译；动态模块（.so）也无法加载——因为没有底层支持
检查 load_module 指令与 .so 文件状态
仅当模块是动态编译（.so）时才需要显式加载；静态模块（如 ssl、http_v2）无需此步，但容易误加导致语法错误。
- 打开主配置文件（如
/etc/nginx/nginx.conf），确认load_module行位于events块之前，且路径正确 - 路径是相对于
prefix的相对路径（默认为/usr/share/nginx或/usr/local/nginx）；可用nginx -V 2>&1 | grep prefix查看 - 执行
ls -l $(nginx -V 2>&1 | grep prefix | awk '{print $2}')/modules/，确认 .so 文件存在且权限为可读（如-rwxr-xr-x）
用 nginx -t 和 -e stderr 定位真实错误点
nginx -t 只能发现语法级问题，而模块缺失常导致指令无法识别；-e stderr 才能暴露初始化阶段的加载失败。
- 先运行
nginx -t，记录报错中的指令名（如lua_code_cache、geoip2）和所在文件行号 - 再手动启动：
nginx -c /etc/nginx/nginx.conf -e stderr，错误会直接打印到终端，常见输出如：
unknown directive "lua_shared_dict"（Lua 模块未编译）
failed to initialize Lua VM（LuaJIT 路径或版本错）
dlopen() "/path/to/module.so" failed: ... undefined symbol（ABI 不兼容） - 若使用 systemd，临时绕过服务单元，避免日志被重定向掩盖关键信息
查 error.log 里的底层线索
即使加了 -e stderr，部分模块加载失败仍只记入 error.log，尤其涉及 OpenSSL、libmaxminddb 等外部依赖时。
- 执行
tail -n 30 /var/log/nginx/error.log，搜索关键词：module、failed to load、dlopen、symbol、relocation error - 关注时间戳是否与最近一次启动吻合；若日志为空，检查
error_log指令指向路径是否存在、Nginx 运行用户是否有写权限 - 对 SSL 或 GeoIP2 类模块，额外验证系统级依赖：
ldd $(which nginx) | grep ssl、dpkg -l | grep libmaxminddb（Debian）或rpm -qa | grep maxmind（RHEL）
