动态模块路径配置错误表现为“unknown directive”或“load_module failed”，核心需确认三件事：模块文件是否存在、load_module是否在main上下文、nginx是否有读取权限；须用绝对路径、检查selinux上下文及版本兼容性。
动态模块路径配置错误，通常表现为 nginx: [emerg] unknown directive "xxx"（如 stream、ssl），或启动时报 load_module failed: ... No such file or directory。这类问题不是语法写错，而是模块文件找不到、加载位置不对或权限受限。核心要确认三件事：模块文件是否存在、load_module 指令是否在正确上下文、Nginx 是否有权限读取该文件。
确认模块文件真实存在且路径准确
动态模块是独立的 .so 文件，必须手动指定完整路径。常见错误是路径拼错、目录不存在或文件名不匹配。
- 先查 Nginx 编译信息，确认模块是否支持动态加载：
nginx -V 2>&1 | grep -E "(with-stream|with-http_ssl_module)"，看到=dynamic才表示可动态加载 - 用
find /usr -name "ngx_http_ssl_module.so" 2>/dev/null或find /opt -name "*stream*.so" 2>/dev/null定位实际模块文件位置；默认安装常在/usr/lib64/nginx/modules/或/usr/local/nginx/modules/ - 检查路径是否写全：不能只写
load_module ngx_http_ssl_module.so;，必须是绝对路径，例如load_module /usr/lib64/nginx/modules/ngx_http_ssl_module.so;
检查 load_module 指令位置和顺序
load_module 只能在 main 上下文（即 nginx.conf 最顶层，events 或 http 块之外）使用，且必须在任何使用该模块指令（如 stream、ssl）之前加载。
- 打开
nginx.conf，确认load_module行位于user、pid等指令之后，但严格在events块之前 - 多个模块需逐行声明，顺序无硬性要求，但建议把基础模块（如 ssl）放前面
- 不要把
load_module放进http、server或location块里——这会直接报错“directive is not allowed here”
验证文件权限与 SELinux 上下文
即使路径对、位置对，Nginx 进程也可能因权限不足无法加载模块，尤其在 CentOS/RHEL 启用 SELinux 的环境。
- 执行
ls -lZ /usr/lib64/nginx/modules/ngx_http_ssl_module.so，查看 SELinux 上下文是否为system_u:object_r:nginx_modules_t:s0；如果不是，用sudo semanage fcontext -a -t nginx_modules_t "/usr/lib64/nginx/modules(/.*)?"+sudo restorecon -Rv /usr/lib64/nginx/modules修复 - 检查文件属主和读权限：
sudo chown root:root *.so且sudo chmod 644 *.so（Nginx 主进程以 root 启动，需能读取） - 临时禁用 SELinux 测试：
sudo setenforce 0，再nginx -t；若通过，说明是策略限制，需按上一步修复而非永久关闭
用 nginx -t 和错误日志精准定位
每次修改后必须运行 sudo nginx -t，它会明确指出哪一行加载失败。结合日志可快速区分是路径错、权限错还是模块版本不匹配。
- 报
open() "/xxx/xxx.so" failed (2: No such file or directory)→ 路径错误或文件被删 - 报
open() "/xxx/xxx.so" failed (13: Permission denied)→ 权限或 SELinux 阻止 - 报
undefined symbol或version mismatch→ 模块与当前 Nginx 版本不兼容（比如用 1.20 编译的模块加载到 1.22） - 错误日志路径可通过
nginx -V 2>&1 | grep conf-path查到，默认为/var/log/nginx/error.log，实时跟踪：sudo tail -f /var/log/nginx/error.log
