模块依赖缺失本质是运行环境缺底层库，如libmaxminddb或luajit；需先用nginx -v确认是否编译进内核，再检查load_module路径权限、ldd依赖库及error.log报错线索。
模块依赖缺失不是配置写错了，而是运行环境缺了底层支撑——比如要加载 ngx_http_geoip2_module，但系统没装 libmaxminddb；想用 Lua 指令却没部署 LuaJIT。这类问题不会直接报“依赖缺失”，而是表现为模块加载失败、指令不认识或服务启动卡在 emerg 阶段。
确认模块本身是否被编译进 Nginx
很多“模块找不到”其实是压根没编译进去。先执行：
-
nginx -V查看输出中的--with-xxx-module（如--with-http_ssl_module）或--add-module=路径 - 若目标模块不在列表里，说明它未参与编译——不能靠后期加载补救，必须重编译或换用已集成该模块的包（如 Ubuntu 的
nginx-full） - 对第三方模块，还要核对其源码是否兼容当前 Nginx 版本（例如部分模块不支持 1.25+）
检查动态模块的显式加载与文件状态
即使模块已编译为 .so 文件，也必须通过 load_module 指令启用，且路径、权限、位置都得对：
-
load_module必须写在events块之前，例如：load_module modules/ngx_http_geoip2_module.so; - 路径是相对于
prefix的（默认如/usr/share/nginx或/usr/local/nginx），可用nginx -p '' -V 2>&1 | grep prefix确认实际前缀 - 执行
ls -l $(nginx -p '' -V 2>&1 | awk '/prefix/{print $2}')/modules/看.so文件是否存在、是否可读（权限至少为644）
验证运行时共享库依赖是否满足
模块能加载，不代表它能跑起来。很多模块依赖外部动态库，缺失时可能静默失败或只在 error.log 中留线索：
- 用
ldd /path/to/module.so检查其依赖的.so是否都能解析（重点关注not found行） - 常见依赖举例：
–ngx_http_geoip2_module→ 需libmaxminddb.so（对应开发包：libmaxminddb-dev）
– Lua 相关模块 → 需libluajit-5.1.so或liblua5.1.so
– Brotli 模块 → 需libbrotlidec.so - 若依赖库在非标准路径（如
/usr/local/lib），需确保/etc/ld.so.conf.d/下有对应配置，并运行sudo ldconfig
结合日志与配置测试定位真实断点
不要只信报错文字。Nginx 启动失败时，错误信息往往滞后或间接：
- 先运行
nginx -t：若报unknown directive "geoip2_country"，就说明ngx_http_geoip2_module没加载成功 - 再查
error.log（通常在/var/log/nginx/error.log），搜索关键词：
–module not found
–failed to load
–dlopen()
–undefined symbol（表示 ABI 不匹配或符号未导出） - 如果
nginx -V显示模块已编译，但nginx -t报错且日志无明确提示，很可能是模块与当前 Nginx 主版本不兼容（比如升级 Nginx 后没重编第三方模块）
