查看 nginx 模块支持的指令,最直接的方法是使用 nginx -v 命令获取编译参数,结合官方文档或源码目录结构进行对照。nginx 的指令支持情况取决于编译时启用了哪些模块,静态编译的模块在配置文件中直接可用,而动态加载的模块需要确保配置文件正确引用。通过检查 nginx -v 输出的 --with- 或 --add-module 参数,可以确定当前实例包含哪些核心模块和第三方模块,进而查阅对应模块的文档以了解其支持的指令集。

如何确认当前 Nginx 已加载了哪些模块
要确认当前运行的 Nginx 实例包含了哪些模块,必须执行 nginx -V 命令(注意是大写 V)。该命令会输出 Nginx 的版本信息以及编译时的所有配置参数。重点关注输出中包含 --with-http_ssl_module、--add-dynamic-module=... 等前缀的参数。这些参数列出了所有静态编译进二进制文件的模块。如果使用了动态模块,还会显示 dynamic modules 部分列出的 .so 文件路径。只有出现在这里的模块,其指令才能在配置文件中被识别和使用。若某模块未在此列表中,尝试使用该模块的指令会导致 Nginx 启动报错,提示未知指令。

nginx -V nginx version: nginx/1.24.0 built by gcc 11.4.0 (Ubuntu 11.4.0-1ubuntu1~22.04) built with OpenSSL 3.0.2 15 Mar 2022 TLS SNI support enabled configure arguments: --prefix=/etc/nginx --sbin-path=/usr/sbin/nginx --modules-path=/usr/lib/nginx/modules --conf-path=/etc/nginx/nginx.conf --error-log-path=/var/log/nginx/error.log --http-log-path=/var/log/nginx/access.log --with-http_gzip_static_module --with-http_ssl_module --with-http_v2_module
运行上述命令后,观察 configure arguments 行。例如,这里显示了 --with-http_ssl_module,说明当前 Nginx 支持 SSL/TLS 相关指令,如 ssl_certificate 和 ssl_protocols。同时,--with-http_v2_module 表明支持 HTTP/2 指令。如果列表中没有 --with-http_lua_module,则不能使用 OpenResty 或 ngx_lua 提供的 lua_code_cache 等指令。通过这种方式,开发者可以精确掌握当前环境的能力边界,避免在配置中写入不被支持的指令。
如何查找特定模块支持的详细指令列表
一旦通过 nginx -V 确定了模块名称,下一步是查找该模块具体支持哪些指令。对于核心模块(如 ngx_http_core_module),指令列表固定且文档完善。对于第三方模块,需访问其 GitHub 仓库或官方文档。每个模块通常有一个 README 文件或专门的指令参考页面,列出所有支持的指令及其语法、默认值和上下文。例如,ngx_http_proxy_module 支持 proxy_pass、proxy_set_header 等指令。开发者应优先查阅官方文档,因为非官方维护的模块可能存在指令差异或版本兼容性 issues。在实际配置时,将找到的指令放入正确的上下文(如 http、server 或 location)块中,即可生效。

# 假设已确认安装了 http_ssl_module
# 在 /etc/nginx/conf.d/example.conf 中使用其指令
server {
listen 443 ssl;
server_name example.com;
# 使用 ssl_certificate 指令,由 http_ssl_module 提供
ssl_certificate /etc/ssl/certs/example.crt;
ssl_certificate_key /etc/ssl/private/example.key;
location / {
proxy_pass http://backend;
}
}
在上述配置示例中,ssl_certificate 和 ssl_certificate_key 是 http_ssl_module 提供的指令。由于之前通过 nginx -V 确认了该模块已编译,因此这些指令可以被正确解析。如果尝试使用一个不存在的模块指令,例如 lua_shared_dict(属于 ngx_lua 模块),而该模块未在 nginx -V 输出中出现,Nginx 将在启动时抛出错误:unknown directive "lua_shared_dict"。这验证了先确认模块存在再使用其指令的重要性。对于动态模块,还需确保在 nginx.conf 中使用 load_module 指令加载对应的 .so 文件,否则即使模块文件存在,其指令也不会被识别。
当配置中出现未知指令错误时如何排查
如果在修改 Nginx 配置文件后重启服务遇到 unknown directive 错误,首要步骤是检查拼写和大小写。Nginx 指令区分大小写,且必须完全匹配文档中的名称。其次,确认该指令所属的模块是否已正确编译并加载。回顾 nginx -V 的输出,看是否有对应的 --with- 或 --add-dynamic-module 参数。如果是动态模块,检查 load_module 语句是否正确指向 .so 文件路径。如果模块确实存在但仍报错,可能是指令放错了上下文。例如,worker_connections 只能放在 events 块中,若放在 http 块中也会报未知指令错误。此时应查阅模块文档,确认指令的有效上下文范围。修正位置或加载缺失模块后,重新测试配置 nginx -t 即可验证修复结果。


















