Docker环境下Nginx load_module指令位置错误报错排查求助

Nginx的load_module是全局级指令，只能放在主配置文件（通常是/etc/nginx/nginx.conf）的最外层（http块之外），不能出现在被include的子配置文件（比如conf.d/default.conf）或http/server等嵌套块中。

你遇到的报错本质是：

1. 把带load_module的配置复制到conf.d/default.conf，而这个文件会被主配置的http块自动引入，导致load_module出现在了http块的作用域内，违反指令作用域规则。
2. 用http包裹全部配置后，相当于在子配置里嵌套了http块，而主配置本身已经有http块，触发重复嵌套的错误。

方案一：拆分配置（推荐） #

将全局指令和业务配置分开，分别复制到对应路径：

1. 自定义主配置文件：创建本地nginx.conf，把load_module放在全局区域，保留默认的http块结构：

# 全局区域：加载模块必须放在这里
load_module /usr/lib/nginx/modules/ndk_http_module.so;
load_module /usr/lib/nginx/modules/ngx_http_set_misc_module.so;

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log notice;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    keepalive_timeout  65;

    include /etc/nginx/conf.d/*.conf;
}

注意：模块路径用绝对路径更稳妥，Docker中Nginx模块默认在/usr/lib/nginx/modules/下，可根据实际镜像调整。

2. 业务配置文件：创建本地conf.d/default.conf，只保留server相关配置：

server {
    listen 80;
    listen [::]:80;

    server_name example.com;
    server_tokens off;
    more_clear_headers 'Server';
    more_clear_headers 'X-Powered-By';

    location / {
        return 301 https://example.com$request_uri;
    }
}

server {
    ...
}

3. 修改Dockerfile：分别复制两个配置文件到对应路径：

COPY ./nginx.conf /etc/nginx/nginx.conf
COPY ./conf.d/default.conf /etc/nginx/conf.d/default.conf

方案二：利用全局级include（如果主配置支持） #

如果你的Nginx主配置默认在全局区域有include /etc/nginx/modules-enabled/*.conf;这类语句，可以单独创建加载模块的配置文件：

1. 本地创建modules-load.conf：

load_module /usr/lib/nginx/modules/ndk_http_module.so;
load_module /usr/lib/nginx/modules/ngx_http_set_misc_module.so;

2. Dockerfile中复制该文件到全局include路径，同时保留业务配置的复制：

COPY ./modules-load.conf /etc/nginx/modules-enabled/modules-load.conf
COPY ./nginx.conf /etc/nginx/conf.d/default.conf

启动容器前，先测试配置是否合法：

docker run --rm -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf -v $(pwd)/conf.d/default.conf:/etc/nginx/conf.d/default.conf nginx nginx -t

输出显示test is successful则配置正确。

内容的提问来源于stack exchange，提问作者Jeanluca Scaljeri