遇到 unknown directive 错误，核心原因是 nginx 配置文件中使用了当前编译版本未包含的模块指令。解决该问题的直接做法是确认缺失的模块名称，然后重新编译 nginx 并添加对应的 --with- 或 --add-module 参数。如果使用的是包管理器安装的 nginx，通常可以通过安装额外的插件包（如 nginx-extras）来解决，无需手动编译。
如何确定缺失的是哪个模块
要确定具体是哪个模块缺失，需要查看 Nginx 的编译历史或当前已加载的模块列表。Nginx 在启动时不会自动加载所有可能的模块，只加载编译时指定的模块。因此，当配置文件中出现一个未被编译进二进制文件的指令时，就会报错。我们可以通过运行 nginx -V 命令来查看当前的编译参数，从而判断是否包含了所需的模块功能。
# 查看当前 Nginx 的编译参数 nginx -V 2>&1 | grep -o 'with-[^ ]*'
假设我们需要使用 ngx_http_geoip_module 提供的 geoip_country 指令，但发现报错。通过上述命令检查，如果发现输出中没有 --with-http_geoip_module，则说明该模块未编译。此时，我们需要下载 Nginx 源码，在配置阶段加入该模块。例如，执行 ./configure --with-http_geoip_module，然后 make 和 make install。注意，重新编译会覆盖现有的 Nginx 二进制文件，建议先备份配置文件和数据目录。
使用包管理器安装额外模块
对于大多数 Linux 发行版，直接使用源码编译较为繁琐，且容易因依赖问题导致环境混乱。更推荐的做法是利用系统包管理器安装包含常用模块的 Nginx 变体。例如，在 Debian/Ubuntu 系统中，默认的 nginx 包可能只包含基础模块。如果需要高级功能，可以安装 nginx-extras 或 libnginx-mod-http-geoip 等包。这些包通常已经预编译了常用的第三方或扩展模块，安装后重启 Nginx 即可生效，无需重新编译源码。
# Ubuntu/Debian 示例 sudo apt-get update sudo apt-get install libnginx-mod-http-geoip # 重启 Nginx 使新模块生效 sudo systemctl restart nginx
在安装额外模块包后，再次运行 nginx -t 进行语法检查。如果之前的 unknown directive 是因为缺少模块导致的，现在应该能够通过检查。如果仍然报错，请仔细核对指令拼写，确保没有大小写错误或拼写错误，因为 Nginx 指令是区分大小写的。此外，某些模块可能需要特定的许可证或来源，确保你使用的模块源是可信的。
基于 geoip_country 指令的具体排查
以 geoip_country 指令为例，这是一个常见的导致 unknown directive 的场景。该指令属于 ngx_http_geoip_module。如果在配置中直接写入 geoip_country /usr/share/GeoIP/GeoIP.dat; 而模块未加载，Nginx 将无法识别。解决此问题的关键在于确保模块已正确加载。在源码编译场景下，需确认 --with-http_geoip_module 参数；在包管理场景下，需安装对应的模块包。安装完成后，务必重启服务，因为模块加载发生在 Nginx 启动阶段。如果重启后仍报错，检查配置文件路径是否正确指向了 GeoIP 数据库文件，并确保 Nginx 进程有权限读取该文件。
