nginx的modules目录不自动加载模块，必须通过main上下文中的load_module指令显式加载.so文件；路径由编译时--modules-path指定，需确保abi兼容、权限正确，并用nginx -t和nginx -s reload验证。
Nginx 的 modules 文件夹本身不会自动加载任何模块——它只是个存放 .so 文件的目录，真正起作用的是 load_module 指令，且必须手动配置。
modules 目录不是“自动扫描加载”的插件目录，而是你指定位置后由 load_module 显式引用的容器。
确认 modules 目录路径
这个路径在编译 Nginx 时由 --modules-path 参数决定，不是固定值。运行以下命令查看实际路径：
nginx -V 2>&1 | grep 'modules-path'
常见默认路径包括：
-
/usr/lib/nginx/modules（Debian/Ubuntu） -
/usr/lib64/nginx/modules（RHEL/CentOS/Fedora） -
/usr/local/nginx/modules（源码安装默认）
你也可以把模块放在任意位置（比如 /opt/nginx-modules/），只要 load_module 指向正确即可。
把动态模块文件放进 modules 目录
- 模块必须是
.so文件（如ngx_http_geoip2_module.so）； - 确保该文件与当前 Nginx ABI 完全兼容：同版本、同编译器、同 OpenSSL/PCRE/zlib；
- 设置可读权限（Nginx 主进程需能读取）：
chmod 644 /usr/lib/nginx/modules/ngx_http_geoip2_module.so
⚠️ 别直接从其他服务器复制
.so文件——即使版本号一样，底层依赖不一致也会导致undefined symbol或启动失败。
在 nginx.conf 中加载模块
load_module 必须写在 main 上下文（即配置文件最顶部，events { } 块之前），不能嵌套在 http、server 或 location 中：
load_module /usr/lib/nginx/modules/ngx_http_geoip2_module.so;
load_module /usr/lib/nginx/modules/ngx_http_headers_more_filter_module.so;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
server {
listen 80;
location / {
more_set_headers "X-GeoIP: enabled";
}
}
}
- 推荐用绝对路径，避免相对路径解析歧义；
- 每个模块单独一行，不可合并或加注释；
- 加载顺序一般无关，但若模块间有隐式依赖（如某模块调用另一模块导出的函数），需按依赖顺序排列。
验证是否加载成功
-
语法检查
nginx -t
若报错
module not found或is not binary compatible，重点查路径、权限、ABI 匹配。 -
重载配置（不是重启）
nginx -s reload
只有
reload会重新解析 main 块并加载新模块；restart不额外生效，还可能中断连接。 -
间接验证是否生效
- 查看错误日志：
tail -f /var/log/nginx/error.log，成功无日志，失败会有明确提示； - 在
http块中使用该模块提供的指令（如geoip2、echo、more_set_headers），然后nginx -t不报错即说明已识别； - 运行
nginx -T 2>/dev/null | grep load_module可确认配置中哪些load_module生效。
- 查看错误日志：
不复杂但容易忽略。
