load_module指令必须置于nginx.conf最顶部（events和http块之前），仅支持动态模块.so文件，路径须绝对或相对于配置文件，且需版本与abi严格匹配。
在 Nginx 的 nginx.conf 中引用第三方模块，核心只有一条指令：load_module，且必须放在配置文件最顶部（events 或 http 块之前），不能嵌套在任何块内。
load_module 指令写法与位置要求
该指令用于加载已编译好的动态模块（.so 文件），语法严格、位置敏感：
- 每行只能写一个
load_module，不可用分号或逗号合并多个 - 路径是相对于 Nginx 安装前缀（
--prefix）的相对路径，例如：load_module modules/ngx_http_geoip2_module.so; - 更推荐使用绝对路径，避免因前缀变更导致加载失败，例如：
load_module /usr/lib64/nginx/modules/ngx_http_headers_more_filter_module.so; - 必须置于
events、http等任何配置块之前；若写在http块内部，Nginx 启动时会报错并拒绝加载
模块加载后如何生效对应功能
仅写 load_module 不代表功能可用，还需在后续配置中显式启用模块提供的指令或功能：
- 比如加载了
headers-more-nginx-module，需在server或location块中使用more_set_headers等指令 - 加载了
ngx_http_geoip2_module，需在http块中配置geoip2指令指向数据库文件 - 若模块无对应配置项（如仅提供内部钩子），则加载即生效，无需额外配置
验证模块是否成功加载
配置修改后不能直接重启，需先验证再重载：
- 执行
nginx -t：提示configuration file /etc/nginx/nginx.conf test is successful表示语法正确 - 执行
nginx -s reload重载配置 - 检查错误日志：
tail -f /var/log/nginx/error.log，无module "xxx" is not binary compatible或undefined symbol报错即为成功 - 运行
nginx -V 2>&1 | grep 'modules/.*\.so'可列出当前加载的动态模块路径
常见误区提醒
很多配置失败源于对机制理解偏差：
-
load_module仅支持动态模块（.so），不适用于静态编译进 Nginx 的模块（那些出现在nginx -V输出中的--with-xxx） - 模块版本必须与当前 Nginx 主版本、ABI 兼容（如 Nginx 1.24.x 编译的 .so 无法用于 1.25.x）
- 模块依赖其他模块时（如某模块需调用 OpenSSL 函数），需确保基础模块已存在且符号可访问，否则报
undefined symbol - 配置里写错路径、权限不足（Nginx worker 进程无法读取 .so 文件）、SELinux 限制等，都会导致静默失败或启动报错
