load_module指令只能出现在全局块中且须在events和http块之前,用于启动时加载兼容的动态模块;路径需为相对或绝对路径,建议用绝对路径,并通过nginx -t和nginx -V --modules验证。
在 Nginx 中,
指令**只能出现在全局块(main context)中**,且必须位于
和
块之前,用于动态加载第三方模块(如
、
等)。它不是运行时热加载机制,而是启动时由主进程读取并初始化模块。
load_module 的位置和语法要求
必须写在配置文件最外层(即全局作用域),不能嵌套在
、
、
或
块内。否则 Nginx 启动会报错:
nginx: [emerg] "load_module" directive is not allowed here
正确写法示例:
模块路径必须是相对或绝对路径
Nginx 不会自动搜索模块。路径是相对于 Nginx 安装目录的
(默认通常是
),也可以写成绝对路径:
Nginx
在宝塔面板中轻松管理Nginx高性能Web服务器。提供可视化配置反向代理、负载均衡、SSL证书及HTTP缓存功能,一键优化高并发性能,助您高效搭建稳定、快速的网站运行环境。
下载
→ 相对路径,等价于
→ 绝对路径,更明确可控
建议使用绝对路径,避免因启动工作目录不同导致加载失败。
模块必须与 Nginx 版本和编译参数兼容
动态模块不是“即插即用”的:
必须由相同版本、相同构建选项(如 OpenSSL 版本、是否启用 PCRE/JNI 等)的 Nginx 源码编译生成
若 Nginx 是通过包管理器(如 apt/yum)安装的,需确认其是否启用了
;否则无法加载第三方动态模块
可通过
查看编译参数,重点关注是否有
验证模块是否加载成功
启动前可先检查配置并查看模块列表:
:验证语法,若模块路径错误或不兼容,会提示类似
:列出所有已编译和已加载的模块(包括动态加载的)
启动后访问
(需启用
)无法直接显示动态模块状态,需依赖模块自身提供的指令或日志确认(如 geoip2 模块启用后可在 log_format 中使用
)
load_moduleeventshttpngx_http_geoip2_modulengx_http_brotli_filter_moduleload_moduleeventshttpserverlocationload_module modules/ngx_http_geoip2_module.so;
load_module modules/ngx_http_brotli_filter_module.so;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
server {
listen 80;
location / {
root html;
}
}
}prefix/usr/local/nginxload_module modules/ngx_http_geoip2_module.so;$NGINX_PREFIX/modules/...load_module /opt/nginx/modules/ngx_http_brotli_filter_module.so;--with-compatnginx -V--with-compatnginx -tmodule "/path/to/module.so" is not binary compatiblenginx -V --moduleshttp://your-server/nginx_statusngx_http_stub_status_module$geoip2_data_country_code