在 nginx 中给已安装的系统动态加载模块，核心做法是编译出对应的 .so 文件，将其放入 modules 目录，并在配置文件中通过 load_module 指令引用。这样做无需重新编译整个 nginx 主程序，也避免了重启时因主程序版本不匹配导致的兼容性问题。只要确保模块的 abi 与当前运行的 nginx 版本一致，即可实现热插拔式的功能扩展。
如何编译并安装一个动态模块
要生成可用的动态模块，必须使用与当前 Nginx 二进制文件完全相同的源码版本进行编译，并指定 --with-compat 参数。这个参数告诉构建系统只生成兼容的二进制接口，而不绑定特定的 Nginx 版本号。编译完成后，生成的 .so 文件通常位于 objs/ 目录下，需要手动复制到 Nginx 的模块目录中。
cd /path/to/nginx-source
./configure --with-compat \
--add-dynamic-module=/path/to/module-source
make modules
sudo cp objs/*.so /etc/nginx/modules/
上述命令执行后，会在 /etc/nginx/modules/ 目录下生成对应的共享对象文件。例如，如果编译的是 ngx_http_geoip2_module，则会生成 ngx_http_geoip2_module.so。此时模块文件已经就绪，但尚未被 Nginx 加载。
如何在配置中启用动态模块
模块文件就位后，需要在 Nginx 的主配置文件或包含的文件中显式声明加载该模块。使用 load_module 指令指向具体的 .so 文件路径。该指令必须放在 events 和 http 块之外，通常位于配置文件的顶部。加载成功后，就可以像使用内置模块一样，在 http 块中使用该模块提供的指令。
# /etc/nginx/nginx.conf
load_module modules/ngx_http_geoip2_module.so;
events {
worker_connections 1024;
}
http {
geoip2 $geoip2_data {
auto_reload 5m;
provider /usr/share/GeoIP/GeoLite2-City.mmdb;
$geoip2_data.country.iso_code country iso_code;
}
# ... 其他配置
}
完成配置后，运行 nginx -t 检查语法是否正确。如果一切正常，执行 nginx -s reload 平滑重载配置即可生效。如果在重载过程中遇到错误，通常是模块版本不匹配或路径错误，需仔细检查 load_module 的路径是否准确指向了刚才复制的 .so 文件。
当 load_module 路径错误时会发生什么
如果 load_module 指定的路径不存在或权限不足，Nginx 在启动或重载配置时会直接报错并拒绝加载配置。这种错误是致命的，因为模块加载发生在配置解析的早期阶段。用户会看到类似 “open() "/etc/nginx/modules/nonexistent.so" failed” 的错误信息，导致服务无法启动或配置更新失败。这种情况下，必须修正路径或确保文件存在且可读，才能恢复服务。
