“unknown directive”错误主因是模块未编译或未加载，而非配置语法错误；需先用nginx -v检查with-stream等参数，区分静态/动态模块，动态模块须在main上下文用load_module显式加载，并确保路径正确、版本兼容。
遇到“unknown directive”或“unrecognized directive”这类报错，核心不是配置写错了，而是Nginx压根不认识这个指令——通常因为对应模块没加载、没编译，或者加载位置不对。
确认模块是否已编译进Nginx
这是最常被跳过的一步。很多系统（如Ubuntu官方源、CentOS最小化安装）默认不带stream、ssl、lua等模块。
- 运行 nginx -V 2>&1 | grep -o with-stream，无输出表示未编译stream模块
- 同理检查SSL：nginx -V 2>&1 | grep -o with-http_ssl_module
- 检查Lua：nginx -V 2>&1 | grep -o with-http-lua-module
区分静态模块与动态模块加载方式
静态模块在编译时就嵌入二进制，无需额外配置；动态模块必须显式用 load_module 加载，且必须放在 main 上下文（即 nginx.conf 最顶部，events 块之前）。
- 若编译参数含 --with-stream=dynamic，需加：load_module modules/ngx_stream_module.so;
- 若提示 module “modules/ngx_stream_module.so” is not binary compatible，说明模块版本与Nginx不匹配，需重装或重编译
- Ubuntu用户常见情况：模块文件在 /usr/lib/nginx/modules/，路径写错会静默失败
验证配置上下文与指令合法性
即使模块存在，指令放错位置也会报“not allowed here”。比如：
- stream 块只能在 main 上下文（不能套在 http 或 server 里）
- proxy_pass 在 stream 块中可用，在 http 的 location 中也有效，但不能出现在 events 或全局顶层
- ssl_certificate 只能在 server 块内使用，且该 server 必须有 listen ... ssl
强制终端输出启动错误，绕过日志延迟
模块加载失败往往发生在初始化早期，error.log 可能为空或没写入。此时用 -e stderr 强制打印到终端：
- nginx -c /etc/nginx/nginx.conf -e stderr
- 你会立刻看到类似：unknown directive "lua_shared_dict" 或 failed to load module "ngx_http_lua_module.so"
- 配合 nginx -T 可查看Nginx实际解析后的完整配置树，确认指令是否被识别、落在哪个作用域
