ModuleNotFoundError本质是Python在sys.path中未找到目标模块，需按四步排查：①确认是否安装；②核对解释器与pip匹配；③验证导入路径和工作目录；④识别虚拟环境干扰。
遇到“模块未找到”或配置中出现 unknown directive 报错，通常不是配置写错了，而是动态模块文件本身缺失、路径不对、权限不足，或加载方式有误。处理核心是分三步确认：模块是否存在、是否被正确加载、是否能被运行时环境识别。
检查模块文件是否真实存在
动态模块是 .so 文件，必须存在于配置中 load_module 指令指定的路径下。常见误区是只复制了模块名，却没确认文件实际在磁盘上。
- 先查 Nginx 的 modules 路径：
nginx -V 2>&1 | grep "modules-path"（若无输出，常用默认路径为/usr/lib/nginx/modules/或/usr/lib64/nginx/modules/） - 再列出该目录下的 .so 文件：
ls -l $(nginx -V 2>&1 | grep "modules-path" | awk -F'=' '{print $2}') | grep your_module - 如果文件不存在，说明还没编译或没复制过去；如果存在但名字不符（比如
ngx_http_geoip2_module.so写成了geoip2.so），也会加载失败
验证 load_module 指令是否合规
load_module 必须出现在配置文件最顶部，在 events 块之前，且路径必须准确——它不支持相对路径简写，也不自动补全后缀。
- 正确写法（推荐绝对路径）：
load_module /usr/lib/nginx/modules/ngx_http_brotli_filter_module.so; - 错误写法举例：
load_module modules/ngx_http_brotli_filter_module;（缺 .so 后缀）、load_module ./modules/...（点号路径不识别）、load_module放在 http 块里（位置错误） - 执行
nginx -t，它会明确提示哪一行 load_module 出错，比如 “module not found in /xxx/xxx.so”，直接按提示路径去检查即可
排查运行时权限与依赖问题
即使 .so 文件存在且路径正确，也可能因权限或底层库缺失而静默失败——此时 error.log 中常出现 dlopen failed、version mismatch 或 cannot open shared object file 等关键词。
- 检查文件权限：
ls -l /path/to/module.so，确保 nginx 进程用户（如 www-data 或 nginx）有读取权限（至少-r-xr-xr-x） - 验证模块依赖：
ldd /path/to/module.so | grep "not found"，若提示如libmaxminddb.so.0 => not found，说明缺少外部运行库 - 对缺失的库，可临时测试：
LD_LIBRARY_PATH=/usr/local/lib nginx -t；长期方案是把库路径写入/etc/ld.so.conf.d/xxx.conf并运行sudo ldconfig
确认 Nginx 主程序支持动态模块
不是所有 Nginx 都能加载 .so。低于 1.9.11 的版本不支持；某些精简包（如 CentOS 的 nginx-1.20.1-1.el8.x86_64）甚至默认禁用动态模块支持。
- 运行
nginx -V 2>&1 | grep dynamic，有输出才表示支持；若无，需更换官方 mainline 包或重新编译主程序 - 再查模块是否被标记为动态编译：
nginx -V 2>&1 | grep "with-http_ssl_module=dynamic"，带=dynamic表示该模块是以 .so 形式构建的 - 若模块本应是静态的（如 --with-stream），却试图用 load_module 加载，也会报错——此时只能重装含该模块的完整版 Nginx
