应先运行nginx -V检查编译参数是否含目标模块（如--with-http_ssl_module），若缺失则需重新编译；再确认动态模块是否通过load_module正确加载且.so文件存在可读；最后用nginx -t定位报错指令，结合error.log中module not found等关键词验证运行时依赖与权限。
当 Nginx 启动失败并报错“module not found”或类似提示（如 unknown directive "xxx"），通常是因模块未正确编译、未加载，或配置中引用了不存在的模块。排查需从编译、配置、运行时三方面入手。
确认 Nginx 是否实际支持该模块
不是所有模块都默认启用。Nginx 分为核心模块（始终可用）、标准扩展模块（需编译时启用）和第三方模块（需手动添加）。
- 运行
nginx -V查看完整编译参数，重点关注--add-module=（第三方模块路径）和--with-xxx-module（如--with-http_ssl_module）是否包含目标模块 - 若输出中没有对应模块，说明它未被编译进当前 Nginx，需重新编译或换用已集成该模块的发行版（如 Ubuntu 的
nginx-full包） - 对第三方模块，检查其源码路径是否存在、是否与当前 Nginx 版本兼容（部分模块不支持 1.25+）
检查模块是否在配置中被正确加载
动态模块（.so 文件）需显式用 load_module 指令加载，否则即使存在也无法使用。
linux-sysadmin
下载
Linux系统管理专家，覆盖12大模块：用户权限、SSH、存储、网络、systemd、防火墙、日志监控、备份恢复、TLS证书、Ansible、容器、IaC。提供配置、验证、加固、监控、备份、自动化、故障排查、回滚闭环。关键词：useradd、sudo、sshd_config、chmod、SEL...
- 打开主配置文件（通常是
/etc/nginx/nginx.conf），确认在events块之前有类似load_module modules/ngx_http_geoip2_module.so;的语句 - 路径必须是相对于
prefix的相对路径（默认 prefix 是/usr/share/nginx或/usr/local/nginx），也可用绝对路径 - 确保 .so 文件真实存在且权限可读（如
ls -l $(nginx -p '' -V 2>&1 | grep 'prefix' | awk '{print $2}')/modules/）
验证配置语法并定位具体错误行
Nginx 不会直接说“模块没找到”，而是报 unknown directive 或 invalid number of arguments —— 这往往就是模块未加载的间接表现。
- 执行
nginx -t测试配置，注意错误信息中的指令名（如geoip2、lua_code_cache）和所在配置文件及行号 - 根据指令名反查所属模块：比如
geoip2属于ngx_http_geoip2_module，lua_*属于openresty/luajit相关模块 - 若
nginx -t报错但nginx -V显示已编译该模块，可能是模块版本与 Nginx 主版本不匹配（常见于从源码升级 Nginx 后未重编第三方模块）
检查运行时依赖与环境一致性
某些模块依赖外部库（如 GeoIP2 需 libmaxminddb，Lua 模块需 LuaJIT），缺失会导致模块加载失败，但错误可能静默或仅在启动日志中体现。
- 查看错误日志：
tail -n 20 /var/log/nginx/error.log，搜索module、failed to load、dlopen等关键词 - 用
ldd /path/to/module.so检查动态链接库是否齐全（尤其注意libmaxminddb.so.0、libluajit-5.1.so.2等） - 确认 SELinux/AppArmor 未拦截模块加载（临时设为 permissive 模式测试）
