模块 ngx_http_core_module

absolute_redirect on;

如果禁用，nginx 发出的重定向将是相对路径。

另请参阅 server_name_in_redirect 和 port_in_redirect 指令。

aio off;

在 FreeBSD 和 Linux 上启用或禁用异步文件 I/O (AIO)。

location /video/ {
    aio            on;
    output_buffers 1 64k;
}

在 FreeBSD 上，AIO 可以从 FreeBSD 4.3 开始使用。在 FreeBSD 11.0 之前，AIO 可以静态链接到内核中

options VFS_AIO

或作为可加载的内核模块动态加载。

kldload aio

在 Linux 上，AIO 可以从内核版本 2.6.22 开始使用。此外，还需要启用 directio，否则读取将是阻塞的。

location /video/ {
    aio            on;
    directio       512;
    output_buffers 1 128k;
}

在 Linux 上，directio 只能用于读取对齐到 512 字节边界（或 XFS 的 4K）的块。文件的非对齐末尾以阻塞模式读取。这同样适用于字节范围请求和非文件开头部分的 FLV 请求：文件开头和结尾处的非对齐数据读取将是阻塞的。

当在 Linux 上同时启用 AIO 和 sendfile 时，对于大于或等于 directio 指令指定大小的文件，使用 AIO；而对于较小大小的文件或禁用 directio 时，则使用 sendfile。

location /video/ {
    sendfile       on;
    aio            on;
    directio       8m;
}

最后，可以使用多线程读取和发送文件（1.7.11），而不会阻塞工作进程。

location /video/ {
    sendfile       on;
    aio            threads;
}

读取和发送文件操作会卸载到指定线程池的线程中。如果省略池名称，则使用名为“default”的池。池名称也可以使用变量设置。

aio threads=pool$disk;

默认情况下，多线程是禁用的，应使用 --with-threads 配置参数启用。目前，多线程仅与 epoll、kqueue 和 eventport 方法兼容。仅在 Linux 上支持多线程发送文件。

另请参阅 sendfile 指令。

aio_write off;

如果启用 aio，则指定是否将其用于写入文件。目前，这仅在使用 aio threads 时有效，并且仅限于写入从代理服务器接收到的临时文件数据。

定义指定位置的替换路径。例如，使用以下配置

location /i/ {
    alias /data/w3/images/;
}

当请求“/i/top.gif”时，将发送文件 /data/w3/images/top.gif。

path 值可以包含变量，但 $document_root 和 $realpath_root 除外。

如果 alias 在使用正则表达式定义的位置内部使用，则此类正则表达式应包含捕获，并且 alias 应引用这些捕获（0.7.40），例如

location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
    alias /data/w3/images/$1;
}

当位置匹配指令值的最后一部分时

location /images/ {
    alias /data/w3/images/;
}

最好使用 root 指令代替。

location /images/ {
    root /data/w3;
}

auth_delay 0s;

延迟处理返回 401 响应码的未经授权请求，以防止在通过密码、子请求结果或JWT限制访问时发生时序攻击。

chunked_transfer_encoding on;

允许在 HTTP/1.1 中禁用分块传输编码。当使用不支持分块编码的软件时，尽管标准有要求，这可能很有用。

client_body_buffer_size 8k|16k;

设置读取客户端请求体的缓冲区大小。如果请求体大于缓冲区，则整个请求体或其一部分会被写入临时文件。默认情况下，缓冲区大小等于两个内存页。在 x86、其他 32 位平台和 x86-64 上是 8K。在其他 64 位平台上通常是 16K。

client_body_in_file_only off;

确定 nginx 是否应将整个客户端请求体保存到文件中。此指令可在调试期间使用，或在使用 $request_body_file 变量或 ngx_http_perl_module 模块的 $r->request_body_file 方法时使用。

当设置为 on 值时，请求处理后临时文件不会被删除。

clean 值将导致请求处理后留下的临时文件被删除。

client_body_in_single_buffer off;

确定 nginx 是否应将整个客户端请求体保存在单个缓冲区中。建议在使用 $request_body 变量时使用此指令，以减少涉及的复制操作次数。

client_body_temp_path client_body_temp;

定义存储包含客户端请求体的临时文件的目录。在指定的目录下最多可以使用三级子目录层次结构。例如，在以下配置中

client_body_temp_path /spool/nginx/client_temp 1 2;

临时文件的路径可能如下所示

/spool/nginx/client_temp/7/45/00000123457

client_body_timeout 60s;

定义读取客户端请求体的超时时间。超时仅针对两次连续读取操作之间的间隔设置，而不是整个请求体的传输时间。如果客户端在此时间内没有传输任何数据，则请求将以 408 (请求超时) 错误终止。

client_header_buffer_size 1k;

设置读取客户端请求头的缓冲区大小。对于大多数请求，1K 字节的缓冲区已足够。但是，如果请求包含较长的 cookie 或来自 WAP 客户端，它可能无法容纳 1K。如果请求行或请求头字段不适合此缓冲区，则会分配由 large_client_header_buffers 指令配置的更大缓冲区。

如果在 server 级别指定此指令，则可以使用默认服务器的值。详细信息请参见“虚拟服务器选择”部分。

client_header_timeout 60s;

定义读取客户端请求头的超时时间。如果客户端在此时间内未传输整个请求头，则请求将以 408 (请求超时) 错误终止。

client_max_body_size 1m;

设置允许的客户端请求体的最大大小。如果请求中的大小超过配置值，则会向客户端返回 413 (请求实体过大) 错误。请注意，浏览器可能无法正确显示此错误。将 size 设置为 0 会禁用对客户端请求体大小的检查。

connection_pool_size 256|512;

允许精确调整每个连接的内存分配。此指令对性能影响极小，通常不应使用。默认情况下，在 32 位平台上大小为 256 字节，在 64 位平台上为 512 字节。

在版本 1.9.8 之前，所有平台上的默认值都是 256。

default_type text/plain;

定义响应的默认 MIME 类型。文件扩展名到 MIME 类型的映射可以通过 types 指令设置。

directio off;

在读取大于或等于指定 size 的文件时，启用使用 O_DIRECT 标志（FreeBSD、Linux）、F_NOCACHE 标志（macOS）或 directio() 函数（Solaris）。此指令会自动禁用（0.7.15）对给定请求使用 sendfile。这对于提供大文件很有用

directio 4m;

或在 Linux 上使用 aio 时很有用。

directio_alignment 512;

设置 directio 的对齐方式。在大多数情况下，512 字节的对齐就足够了。但是，在 Linux 下使用 XFS 时，需要将其增加到 4K。

disable_symlinks off;

确定打开文件时应如何处理符号链接

off

允许路径名中的符号链接且不检查。这是默认行为。

on

如果路径名的任何组成部分是符号链接，则拒绝访问文件。

if_not_owner

如果路径名的任何组成部分是符号链接，并且该链接及其指向的对象具有不同的所有者，则拒绝访问文件。

from=part

检查符号链接时（参数 on 和 if_not_owner），通常会检查路径名的所有组成部分。可以通过额外指定 from=part 参数来避免检查路径名初始部分的符号链接。在这种情况下，仅检查指定初始部分之后的路径名组成部分中的符号链接。如果该值不是被检查路径名的初始部分，则会像根本未指定此参数一样检查整个路径名。如果该值匹配整个文件名，则不检查符号链接。参数值可以包含变量。

示例

disable_symlinks on from=$document_root;

此指令仅在具有 openat() 和 fstatat() 接口的系统上可用。此类系统包括现代版本的 FreeBSD、Linux 和 Solaris。

参数 on 和 if_not_owner 会增加处理开销。

在不支持仅用于搜索而打开目录的系统上，使用这些参数需要工作进程对所有被检查的目录具有读取权限。

ngx_http_autoindex_module、ngx_http_random_index_module 和 ngx_http_dav_module 模块目前会忽略此指令。

定义指定错误将显示的 URI。uri 值可以包含变量。

示例

error_page 404             /404.html;
error_page 500 502 503 504 /50x.html;

这会导致内部重定向到指定的 uri，并将客户端请求方法更改为“GET”（对于除“GET”和“HEAD”之外的所有方法）。

此外，可以使用“=response”语法将响应码更改为其他代码，例如

error_page 404 =200 /empty.gif;

如果错误响应由代理服务器或 FastCGI/uwsgi/SCGI/gRPC 服务器处理，并且该服务器可能返回不同的响应码（例如 200、302、401 或 404），则可以使用其返回的代码进行响应

error_page 404 = /404.php;

如果在内部重定向期间无需更改 URI 和方法，则可以将错误处理传递给命名位置

location / {
    error_page 404 = @fallback;
}

location @fallback {
    proxy_pass http://backend;
}

如果处理 uri 导致错误，则会将最后发生的错误的状态码返回给客户端。

也可以使用 URL 重定向进行错误处理

error_page 403      http://example.com/forbidden.html;
error_page 404 =301 http://example.com/notfound.html;

在这种情况下，默认情况下会向客户端返回响应码 302。只能更改为重定向状态码之一（301、302、303、307 和 308）。

直到版本 1.1.16 和 1.0.13，代码 307 才被视为重定向。

直到版本 1.13.0，代码 308 才被视为重定向。

这些指令仅在当前级别未定义 error_page 指令时，才会从上一配置级别继承。

etag on;

启用或禁用为静态资源自动生成“ETag”响应头字段。

提供用于指定 HTTP 服务器指令的配置文件上下文。

if_modified_since exact;

指定如何将响应的修改时间与“If-Modified-Since”请求头字段中的时间进行比较

off

响应始终被视为已修改 (0.7.34)；

exact

精确匹配；

before

响应的修改时间小于或等于“If-Modified-Since”请求头字段中的时间。

ignore_invalid_headers on;

控制是否应忽略名称无效的头字段。有效名称由英文字母、数字、连字符组成，并可能包含下划线（由 underscores_in_headers 指令控制）。

如果在 server 级别指定此指令，则可以使用默认服务器的值。详细信息请参见“虚拟服务器选择”部分。

指定给定位置只能用于内部请求。对于外部请求，返回客户端错误 404 (未找到)。内部请求如下所示

• 由 error_page、index、internal_redirect、random_index 和 try_files 指令重定向的请求；
• 由上游服务器响应头字段“X-Accel-Redirect”重定向的请求；
• 由 ngx_http_ssi_module 模块的“include virtual”命令、ngx_http_addition_module 模块指令以及 auth_request 和 mirror 指令形成的子请求；
• 由 rewrite 指令更改的请求。

示例

error_page 404 /404.html;

location = /404.html {
    internal;
}

每个请求的内部重定向次数限制为 10 次，以防止在错误配置中可能出现的请求处理循环。如果达到此限制，则返回错误 500 (内部服务器错误)。在这种情况下，可以在错误日志中看到“rewrite or internal redirection cycle”消息。

keepalive_disable msie6;

禁用与行为异常浏览器的 keep-alive 连接。browser 参数指定哪些浏览器将受到影响。值 msie6 在接收到 POST 请求后禁用与旧版本 MSIE 的 keep-alive 连接。值 safari 禁用与 macOS 和类似 macOS 操作系统上的 Safari 和类似 Safari 浏览器的 keep-alive 连接。值 none 启用与所有浏览器的 keep-alive 连接。

在版本 1.1.18 之前，值 safari 匹配所有操作系统上的所有 Safari 和类似 Safari 浏览器，并且默认禁用与它们的 keep-alive 连接。

keepalive_min_timeout 0;

设置一个超时时间，在此期间，为了连接重用或在工作进程平滑关闭时，服务器端不会关闭 keep-alive 客户端连接。

keepalive_requests 1000;

设置通过一个 keep-alive 连接可以服务的最大请求数。达到最大请求数后，连接将被关闭。

定期关闭连接对于释放每个连接的内存分配是必要的。因此，使用过高的最大请求数可能导致过多的内存使用，不推荐这样做。

在版本 1.19.10 之前，默认值为 100。

keepalive_time 1h;

限制通过一个 keep-alive 连接处理请求的最长时间。达到此时间后，连接将在后续请求处理后关闭。

keepalive_timeout 75s;

第一个参数设置 keep-alive 客户端连接在服务器端保持打开状态的超时时间。零值禁用 keep-alive 客户端连接。可选的第二个参数在“Keep-Alive: timeout=time”响应头字段中设置一个值。两个参数可以不同。

“Keep-Alive: timeout=time”头字段被 Mozilla 和 Konqueror 识别。MSIE 会在大约 60 秒内自行关闭 keep-alive 连接。

large_client_header_buffers 4 8k;

设置用于读取大型客户端请求头的缓冲区的最大 number 和 size。请求行不能超过一个缓冲区的大小，否则会向客户端返回 414 (请求 URI 过大) 错误。请求头字段也不能超过一个缓冲区的大小，否则会向客户端返回 400 (错误请求) 错误。缓冲区仅在需要时分配。默认情况下，缓冲区大小等于 8K 字节。如果在请求处理结束后连接转换到 keep-alive 状态，这些缓冲区将被释放。

如果在 server 级别指定此指令，则可以使用默认服务器的值。详细信息请参见“虚拟服务器选择”部分。

限制位置内允许的 HTTP 方法。method 参数可以是以下之一：GET、HEAD、POST、PUT、DELETE、MKCOL、COPY、MOVE、OPTIONS、PROPFIND、PROPPATCH、LOCK、UNLOCK 或 PATCH。允许 GET 方法也会允许 HEAD 方法。可以使用 ngx_http_access_module、ngx_http_auth_basic_module 和 ngx_http_auth_jwt_module (1.13.10) 模块指令限制对其他方法的访问

limit_except GET {
    allow 192.168.1.0/32;
    deny  all;
}

请注意，这将限制对除 GET 和 HEAD 之外的所有方法的访问。

limit_rate 0;

限制向客户端传输响应的速率。rate 以字节/秒为单位指定。零值禁用速率限制。限制是按请求设置的，因此如果客户端同时打开两个连接，总速率将是指定限制的两倍。

参数值可以包含变量 (1.17.0)。在需要根据特定条件限制速率的情况下可能很有用

map $slow $rate {
    1     4k;
    2     8k;
}

limit_rate $rate;

速率限制也可以在 $limit_rate 变量中设置，但自版本 1.17.0 起，不推荐使用此方法

server {

    if ($slow) {
        set $limit_rate 4k;
    }

    ...
}

速率限制也可以在代理服务器响应的“X-Accel-Limit-Rate”头字段中设置。可以使用 proxy_ignore_headers、fastcgi_ignore_headers、uwsgi_ignore_headers 和 scgi_ignore_headers 指令禁用此功能。

limit_rate_after 0;

设置初始传输量，在此之后向客户端传输响应将受到速率限制。参数值可以包含变量 (1.17.0)。

示例

location /flv/ {
    flv;
    limit_rate_after 500k;
    limit_rate       50k;
}

lingering_close on;

控制 nginx 如何关闭客户端连接。

默认值“on”指示 nginx 在完全关闭连接之前等待并处理来自客户端的额外数据，但仅当启发式判断表明客户端可能正在发送更多数据时。

值“always”将导致 nginx 无条件地等待并处理额外的客户端数据。

值“off”告诉 nginx 永远不要等待更多数据并立即关闭连接。此行为破坏了协议，在正常情况下不应使用。

要控制关闭 HTTP/2 连接，指令必须在 server 级别指定 (1.19.1)。

lingering_time 30s;

当 lingering_close 生效时，此指令指定 nginx 处理（读取并忽略）来自客户端的额外数据的最长时间。之后，即使还有更多数据，连接也将被关闭。

lingering_timeout 5s;

当 lingering_close 生效时，此指令指定等待更多客户端数据到达的最长等待时间。如果在此期间没有收到数据，则连接将被关闭。否则，数据将被读取并忽略，然后 nginx 再次开始等待更多数据。这个“等待-读取-忽略”循环会重复，但不会超过 lingering_time 指令指定的时间。

listen *:80 | *:8000;

设置服务器将接受请求的 IP 地址和端口 address:port，或 UNIX 域套接字的路径 path。可以指定 address 和 port，或仅指定 address 或仅指定 port。address 也可以是主机名，例如

listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;

IPv6 地址 (0.7.36) 写在方括号中

listen [::]:8000;
listen [::1];

UNIX 域套接字 (0.8.21) 使用“unix:”前缀指定

listen unix:/var/run/nginx.sock;

如果只给出 address，则使用端口 80。

如果此指令不存在，则在 nginx 以超级用户权限运行时使用 *:80，否则使用 *:8000。

如果存在 default_server 参数，它将使该服务器成为指定 address:port 对的默认服务器。如果所有指令中都没有 default_server 参数，则第一个具有 address:port 对的服务器将成为此对的默认服务器。

在版本 0.8.21 之前，此参数简称为 default。

ssl 参数 (0.7.14) 允许指定在此端口上接受的所有连接应在 SSL 模式下工作。这使得处理 HTTP 和 HTTPS 请求的服务器的配置更紧凑。

http2 参数 (1.9.5) 配置端口以接受 HTTP/2 连接。通常，为此工作，也应指定 ssl 参数，但 nginx 也可以配置为接受不带 SSL 的 HTTP/2 连接。

此参数已弃用，应改用 http2 指令。

quic 参数 (1.25.0) 配置端口以接受 QUIC 连接。

proxy_protocol 参数 (1.5.12) 允许指定在此端口上接受的所有连接应使用 PROXY 协议。

PROXY 协议版本 2 自版本 1.13.11 起受支持。

listen 指令可以有几个与套接字相关的系统调用特定的附加参数。这些参数可以在任何 listen 指令中指定，但对于给定的 address:port 对只能指定一次。

在版本 0.8.21 之前，它们只能与 default 参数一起在 listen 指令中指定。

setfib=number

此参数 (0.8.44) 为监听套接字设置关联的路由表 FIB（SO_SETFIB 选项）。目前仅在 FreeBSD 上有效。

fastopen=number

为监听套接字启用“TCP Fast Open”（1.5.8），并限制尚未完成三次握手的连接队列的最大长度。

除非服务器可以处理多次接收带数据的相同 SYN 包，否则不要启用此功能。

backlog=number

在 listen() 调用中设置 backlog 参数，该参数限制待处理连接队列的最大长度。默认情况下，backlog 在 FreeBSD、DragonFly BSD 和 macOS 上设置为 -1，在其他平台上设置为 511。

rcvbuf=size

为监听套接字设置接收缓冲区大小（SO_RCVBUF 选项）。

sndbuf=size

为监听套接字设置发送缓冲区大小（SO_SNDBUF 选项）。

accept_filter=filter

为监听套接字设置接受过滤器名称（SO_ACCEPTFILTER 选项），该过滤器在将传入连接传递给 accept() 之前对其进行过滤。这仅在 FreeBSD 和 NetBSD 5.0+ 上有效。可能的值为 dataready 和 httpready。

deferred

指示在 Linux 上使用延迟 accept()（TCP_DEFER_ACCEPT 套接字选项）。

bind

指示对给定的 address:port 对进行单独的 bind() 调用。这很有用，因为如果存在多个具有相同端口但不同地址的 listen 指令，并且其中一个 listen 指令监听给定端口的所有地址（*:port），则 nginx 将仅 bind() 到 *:port。应注意，在这种情况下会进行 getsockname() 系统调用以确定接受连接的地址。如果使用了 setfib、fastopen、backlog、rcvbuf、sndbuf、accept_filter、deferred、ipv6only、reuseport 或 so_keepalive 参数，则对于给定的 address:port 对，总是会进行单独的 bind() 调用。

ipv6only=on|off

此参数 (0.7.42)（通过 IPV6_V6ONLY 套接字选项）确定监听通配符地址 [::] 的 IPv6 套接字是仅接受 IPv6 连接还是同时接受 IPv6 和 IPv4 连接。此参数默认开启。只能在启动时设置一次。

在版本 1.3.4 之前，如果省略此参数，则对套接字生效的是操作系统的设置。

reuseport

此参数 (1.9.1) 指示为每个工作进程创建一个单独的监听套接字（在 Linux 3.9+ 和 DragonFly BSD 上使用 SO_REUSEPORT 套接字选项，或在 FreeBSD 12+ (1.15.1) 上使用 SO_REUSEPORT_LB），允许内核在工作进程之间分配传入连接。目前仅在 Linux 3.9+、DragonFly BSD 和 FreeBSD 12+ (1.15.1) 上有效。

不当使用此选项可能会带来安全隐患。

so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]

此参数 (1.1.11) 配置监听套接字的“TCP keepalive”行为。如果省略此参数，则套接字将遵循操作系统的设置。如果将其值设置为“on”，则会为套接字开启 SO_KEEPALIVE 选项。如果将其值设置为“off”，则会为套接字关闭 SO_KEEPALIVE 选项。某些操作系统支持使用 TCP_KEEPIDLE、TCP_KEEPINTVL 和 TCP_KEEPCNT 套接字选项在每个套接字基础上设置 TCP keepalive 参数。在这些系统上（目前包括 Linux 2.4+、NetBSD 5+ 和 FreeBSD 9.0-STABLE），可以使用 keepidle、keepintvl 和 keepcnt 参数进行配置。可以省略一个或两个参数，在这种情况下，相应的套接字选项将采用系统默认设置。例如，

so_keepalive=30m::10

将空闲超时 (TCP_KEEPIDLE) 设置为 30 分钟，探测间隔 (TCP_KEEPINTVL) 保留其系统默认值，并将探测计数 (TCP_KEEPCNT) 设置为 10 个探测。

示例

listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

根据请求 URI 设置配置。

匹配是针对标准化 URI 进行的，该 URI 经过解码“%XX”形式编码的文本、解析相对路径组件“.”和“..”的引用，以及可能将两个或多个相邻斜杠压缩为一个斜杠。

一个 location 可以通过前缀字符串或正则表达式来定义。正则表达式通过在前面加上“~*”修饰符（用于不区分大小写的匹配）或“~”修饰符（用于区分大小写的匹配）来指定。为了找到匹配给定请求的 location，nginx 首先检查使用前缀字符串定义的 location（前缀 location）。在这些 location 中，选择并记住最长匹配前缀的 location。然后按照它们在配置文件中出现的顺序检查正则表达式。正则表达式的搜索在第一个匹配项处终止，并使用相应的配置。如果没有找到与正则表达式的匹配项，则使用之前记住的前缀 location 的配置。

location 块可以嵌套，但下文提到的一些例外情况除外。

对于不区分大小写的操作系统，例如 macOS 和 Cygwin，与前缀字符串的匹配会忽略大小写 (0.7.7)。但是，比较仅限于单字节区域设置。

正则表达式可以包含捕获 (0.7.40)，这些捕获稍后可以在其他指令中使用。

如果最长匹配前缀 location 带有“^~”修饰符，则不会检查正则表达式。

此外，使用“=”修饰符可以定义 URI 和 location 的精确匹配。如果找到精确匹配，搜索将终止。例如，如果“/”请求频繁发生，定义“location = /”将加速这些请求的处理，因为搜索在第一次比较后就终止了。此类 location 显然不能包含嵌套 location。

在 0.7.1 至 0.8.41 版本中，如果请求匹配了不带“=”和“^~”修饰符的前缀 location，搜索也会终止并且不会检查正则表达式。

我们通过一个例子来说明上述内容

location = / {
    [ configuration A ]
}

location / {
    [ configuration B ]
}

location /documents/ {
    [ configuration C ]
}

location ^~ /images/ {
    [ configuration D ]
}

location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

“/”请求将匹配配置 A，“/index.html”请求将匹配配置 B，“/documents/document.html”请求将匹配配置 C，“/images/1.gif”请求将匹配配置 D，“/documents/1.jpg”请求将匹配配置 E。

“@”前缀定义了命名 location。此类 location 不用于常规请求处理，而是用于请求重定向。它们不能嵌套，也不能包含嵌套 location。

如果 location 是由以斜杠字符结尾的前缀字符串定义的，并且请求由 proxy_pass、fastcgi_pass、uwsgi_pass、scgi_pass、memcached_pass 或 grpc_pass 之一处理，则会执行特殊处理。对于 URI 等于此字符串但不带尾随斜杠的请求，将返回带有代码 301 的永久重定向到附加斜杠的请求 URI。如果这不是期望行为，可以像这样定义 URI 和 location 的精确匹配

location /user/ {
    proxy_pass http://user.example.com;
}

location = /user {
    proxy_pass http://login.example.com;
}

log_not_found on;

启用或禁用将有关找不到文件的错误记录到 error_log。

log_subrequest off;

启用或禁用将子请求记录到 access_log。

限制字节范围请求中允许的最大范围数量。超出限制的请求将按照未指定字节范围进行处理。默认情况下，范围数量不受限制。零值完全禁用字节范围支持。

merge_slashes on;

启用或禁用将 URI 中两个或多个相邻斜杠压缩为一个斜杠。

请注意，压缩对于正确匹配前缀字符串和正则表达式 location 至关重要。如果没有它，“//scripts/one.php”请求将不匹配

location /scripts/ {
    ...
}

并可能被当作静态文件处理。因此它被转换为“/scripts/one.php”。

如果 URI 包含 base64 编码的名称，则关闭压缩可能变得必要，因为 base64 内部使用“/”字符。然而，出于安全考虑，最好避免关闭压缩。

如果在 server 级别指定此指令，则可以使用默认服务器的值。详细信息请参见“虚拟服务器选择”部分。

msie_padding on;

启用或禁用向状态大于 400 的 MSIE 客户端响应中添加注释，以将响应大小增加到 512 字节。

msie_refresh off;

启用或禁用为 MSIE 客户端发送刷新而不是重定向。

open_file_cache off;

配置一个可以存储以下内容的缓存

• 打开的文件描述符、它们的大小和修改时间；
• 关于目录存在的信息；
• 文件查找错误，例如“文件未找到”、“没有读取权限”等等。

  错误缓存应通过 open_file_cache_errors 指令单独启用。

该指令有以下参数

max

设置缓存中元素的最大数量；在缓存溢出时，最近最少使用（LRU）的元素将被移除；

inactive

定义一个时间，在此时间后，如果某个元素在此期间未被访问，则将其从缓存中移除；默认是 60 秒；

off

禁用缓存。

示例

open_file_cache          max=1000 inactive=20s;
open_file_cache_valid    30s;
open_file_cache_min_uses 2;
open_file_cache_errors   on;

open_file_cache_errors off;

启用或禁用通过 open_file_cache 缓存文件查找错误。

open_file_cache_min_uses 1;

设置在由 open_file_cache 指令的 inactive 参数配置的周期内，文件描述符保持在缓存中打开所需的最小文件访问次数。

open_file_cache_valid 60s;

设置 open_file_cache 元素应被验证的时间间隔。

output_buffers 2 32k;

设置用于从磁盘读取响应的缓冲区的数量和大小。

在版本 1.9.5 之前，默认值是 1 32k。

port_in_redirect on;

启用或禁用在 nginx 发出的绝对重定向中指定端口。

在重定向中使用主服务器名称由 server_name_in_redirect 指令控制。

postpone_output 1460;

如果可能，客户端数据的传输将被推迟，直到 nginx 至少有 size 字节的数据可发送。零值禁用数据传输推迟。

read_ahead 0;

设置内核在处理文件时的预读量。

在 Linux 上，使用 posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL) 系统调用，因此 size 参数会被忽略。

在 FreeBSD 上，使用 fcntl(O_READAHEAD, size) 系统调用，该调用从 FreeBSD 9.0-CURRENT 开始支持。FreeBSD 7 需要打补丁。

recursive_error_pages off;

启用或禁用使用 error_page 指令进行多次重定向。此类重定向的数量是有限的。

request_pool_size 4k;

允许精确调整每个请求的内存分配。此指令对性能影响最小，通常不应使用。

reset_timedout_connection off;

启用或禁用重置超时连接和使用非标准代码 444 (1.15.2) 关闭的连接。重置执行如下。在关闭套接字之前，在其上设置 SO_LINGER 选项，超时值为 0。当套接字关闭时，TCP RST 被发送到客户端，并且此套接字占用的所有内存被释放。这有助于避免长时间保持已关闭但缓冲区已满的套接字处于 FIN_WAIT1 状态。

应该注意的是，超时 keep-alive 连接是正常关闭的。

配置用于解析上游服务器名称为地址的名称服务器，例如

resolver 127.0.0.1 [::1]:5353;

地址可以指定为域名或 IP 地址，并带有可选端口 (1.3.1, 1.2.2)。如果未指定端口，则使用端口 53。名称服务器以轮询方式查询。

在版本 1.1.7 之前，只能配置单个名称服务器。从版本 1.3.1 和 1.2.2 开始支持使用 IPv6 地址指定名称服务器。

默认情况下，nginx 在解析时会查找 IPv4 和 IPv6 地址。如果不需要查找 IPv4 或 IPv6 地址，可以指定 ipv4=off (1.23.1) 或 ipv6=off 参数。

从版本 1.5.8 开始支持将名称解析为 IPv6 地址。

默认情况下，nginx 使用响应的 TTL 值缓存答案。可选的 valid 参数允许覆盖它

resolver 127.0.0.1 [::1]:5353 valid=30s;

在版本 1.1.9 之前，无法调整缓存时间，nginx 始终将答案缓存 5 分钟。

为了防止 DNS 欺骗，建议在适当安全可信的本地网络中配置 DNS 服务器。

可选的 status_zone 参数 (1.17.1) 允许在指定的 zone 中收集请求和响应的 DNS 服务器统计信息。该参数作为我们的商业订阅的一部分提供。

resolver_timeout 30s;

设置名称解析超时时间，例如

resolver_timeout 5s;

root html;

设置请求的根目录。例如，通过以下配置

location /i/ {
    root /data/w3;
}

响应“/i/top.gif”请求时将发送文件 /data/w3/i/top.gif。

path 值可以包含变量，但 $document_root 和 $realpath_root 除外。

文件路径通过简单地将 URI 添加到 root 指令的值来构造。如果需要修改 URI，应使用 alias 指令。

satisfy all;

如果 ngx_http_access_module、ngx_http_auth_basic_module、ngx_http_auth_request_module、ngx_http_auth_jwt_module (1.13.10) 或 ngx_http_auth_oidc_module (1.27.4) 模块中的所有 (all) 或至少一个 (any) 模块允许访问，则允许访问。

示例

location / {
    satisfy any;

    allow 192.168.1.0/32;
    deny  all;

    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}

send_lowat 0;

如果指令设置为非零值，nginx 将尝试通过使用 kqueue 方法的 NOTE_LOWAT 标志或 SO_SNDLOWAT 套接字选项，来最小化客户端套接字上的发送操作次数。在这两种情况下都使用指定的 size。

此指令在 Linux、Solaris 和 Windows 上被忽略。

send_timeout 60s;

设置向客户端传输响应的超时时间。超时仅设置在两次连续写入操作之间，而不是针对整个响应传输。如果客户端在此时间内未收到任何内容，则连接将被关闭。

sendfile off;

启用或禁用 sendfile() 的使用。

从 nginx 0.8.12 和 FreeBSD 5.2.1 开始，aio 可用于为 sendfile() 预加载数据

location /video/ {
    sendfile       on;
    tcp_nopush     on;
    aio            on;
}

在此配置中，调用 sendfile() 时带有 SF_NODISKIO 标志，这使其在磁盘 I/O 上不阻塞，而是报告数据不在内存中。然后 nginx 通过读取一个字节启动异步数据加载。在第一次读取时，FreeBSD 内核将文件的前 128K 字节加载到内存中，尽管后续读取将仅加载 16K 块中的数据。这可以通过 read_ahead 指令更改。

在版本 1.7.11 之前，可以通过 aio sendfile; 启用预加载。

sendfile_max_chunk 2m;

限制在一次 sendfile() 调用中可以传输的数据量。没有限制的情况下，一个快速连接可能会完全占用工作进程。

在版本 1.21.4 之前，默认没有限制。

设置虚拟服务器的配置。基于 IP 地址（基于 IP 地址）和基于名称（基于“Host”请求头字段）的虚拟服务器之间没有明确区分。相反，listen 指令描述了应接受服务器连接的所有地址和端口，而 server_name 指令列出了所有服务器名称。示例配置在“nginx 如何处理请求”文档中提供。

server_name "";

设置虚拟服务器的名称，例如

server {
    server_name example.com www.example.com;
}

第一个名称成为主服务器名称。

服务器名称可以包含星号（“*”）代替名称的第一个或最后一个部分

server {
    server_name example.com *.example.com www.example.*;
}

此类名称称为通配符名称。

上述名称的前两个可以合并为一个

server {
    server_name .example.com;
}

在服务器名称中使用正则表达式也是可能的，方法是在名称前加上波浪号（“~”）

server {
    server_name www.example.com ~^www\d+\.example\.com$;
}

正则表达式可以包含捕获 (0.7.40)，这些捕获稍后可以在其他指令中使用

server {
    server_name ~^(www\.)?(.+)$;

    location / {
        root /sites/$2;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

正则表达式中的命名捕获会创建变量 (0.8.25)，这些变量稍后可以在其他指令中使用

server {
    server_name ~^(www\.)?(?<domain>.+)$;

    location / {
        root /sites/$domain;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

如果指令的参数设置为“$hostname” (0.9.4)，将插入机器的主机名。

指定一个空服务器名称 (0.7.11) 也是可能的

server {
    server_name www.example.com "";
}

它允许此服务器处理不带“Host”头字段的请求，而不是默认服务器，对于给定的地址:端口对。这是默认设置。

在 0.8.48 之前，默认使用机器的主机名。

在按名称搜索虚拟服务器期间，如果名称匹配多个指定变体（例如，同时匹配通配符名称和正则表达式），将按以下优先级顺序选择第一个匹配的变体

1. 精确名称
2. 以星号开头的最长通配符名称，例如“*.example.com”
3. 以星号结尾的最长通配符名称，例如“mail.*”
4. 第一个匹配的正则表达式（按其在配置文件中出现的顺序）

关于服务器名称的详细描述在单独的服务器名称文档中提供。

server_name_in_redirect off;

启用或禁用在 nginx 发出的绝对重定向中使用由 server_name 指令指定的主服务器名称。当禁用主服务器名称的使用时，使用“Host”请求头字段中的名称。如果此字段不存在，则使用服务器的 IP 地址。

在重定向中使用端口由 port_in_redirect 指令控制。

server_names_hash_bucket_size 32|64|128;

设置服务器名称哈希表的桶大小。默认值取决于处理器的缓存行大小。关于设置哈希表的详细信息在单独的文档中提供。

server_names_hash_max_size 512;

设置服务器名称哈希表的最大大小。关于设置哈希表的详细信息在单独的文档中提供。

server_tokens on;

启用或禁用在错误页面和“Server”响应头字段中输出 nginx 版本。

build 参数 (1.11.10) 启用在 nginx 版本旁边输出构建名称。

此外，作为我们的商业订阅的一部分，从版本 1.9.13 开始，错误页面上的签名和“Server”响应头字段值可以使用包含变量的string显式设置。空字符串禁用“Server”字段的输出。

subrequest_output_buffer_size 4k|8k;

设置用于存储子请求响应正文的缓冲区大小。默认情况下，缓冲区大小等于一个内存页。这取决于平台，可能是 4K 或 8K。然而，可以使其更小。

此指令仅适用于将响应正文保存到内存的子请求。例如，此类子请求由 SSI 创建。

tcp_nodelay on;

启用或禁用 TCP_NODELAY 选项的使用。当连接转换为 keep-alive 状态时，此选项被启用。此外，它在 SSL 连接上、非缓冲代理和 WebSocket 代理中启用。

tcp_nopush off;

在 FreeBSD 上启用或禁用 TCP_NOPUSH 套接字选项，或在 Linux 上启用或禁用 TCP_CORK 套接字选项。仅在使用 sendfile 时启用这些选项。启用此选项允许

• 在 Linux 和 FreeBSD 4.* 上，在一个包中发送响应头和文件开头；
• 发送完整的数据包文件。

检查按指定顺序存在的文件，并使用找到的第一个文件进行请求处理；处理在当前上下文进行。文件路径根据 root 和 alias 指令，由 file 参数构造。可以通过在名称末尾指定斜杠来检查目录是否存在，例如“$uri/”。如果没有找到任何文件，则对最后一个参数中指定的 uri 进行内部重定向。例如

location /images/ {
    try_files $uri /images/default.gif;
}

location = /images/default.gif {
    expires 30s;
}

最后一个参数也可以指向命名 location，如下例所示。从版本 0.7.51 开始，最后一个参数也可以是 code

location / {
    try_files $uri $uri/index.html $uri.html =404;
}

Mongrel 代理示例

location / {
    try_files /system/maintenance.html
              $uri $uri/index.html $uri.html
              @mongrel;
}

location @mongrel {
    proxy_pass http://mongrel;
}

Drupal/FastCGI 示例

location / {
    try_files $uri $uri/ @drupal;
}

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    fastcgi_param SCRIPT_NAME     $fastcgi_script_name;
    fastcgi_param QUERY_STRING    $args;

    ... other fastcgi_param's
}

location @drupal {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    fastcgi_param SCRIPT_NAME     /index.php;
    fastcgi_param QUERY_STRING    q=$uri&$args;

    ... other fastcgi_param's
}

在以下示例中，

location / {
    try_files $uri $uri/ @drupal;
}

try_files 指令等同于

location / {
    error_page 404 = @drupal;
    log_not_found off;
}

在这里，

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;

    ...
}

try_files 在将请求传递给 FastCGI 服务器之前检查 PHP 文件是否存在。

Wordpress 和 Joomla 示例

location / {
    try_files $uri $uri/ @wordpress;
}

location ~ \.php$ {
    try_files $uri @wordpress;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    ... other fastcgi_param's
}

location @wordpress {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    ... other fastcgi_param's
}

types {
    text/html  html;
    image/gif  gif;
    image/jpeg jpg;
}

将文件名扩展名映射到响应的 MIME 类型。扩展名不区分大小写。多个扩展名可以映射到一个类型，例如

types {
    application/octet-stream bin exe dll;
    application/octet-stream deb;
    application/octet-stream dmg;
}

一个足够完整的映射表随 nginx 一起分发在 conf/mime.types 文件中。

为了让特定的 location 为所有请求发出“application/octet-stream”MIME 类型，可以使用以下配置

location /download/ {
    types        { }
    default_type application/octet-stream;
}

types_hash_bucket_size 64;

设置类型哈希表的桶大小。关于设置哈希表的详细信息在单独的文档中提供。

在版本 1.5.13 之前，默认值取决于处理器的缓存行大小。

types_hash_max_size 1024;

设置类型哈希表的最大大小。关于设置哈希表的详细信息在单独的文档中提供。

underscores_in_headers off;

启用或禁用在客户端请求头字段中使用下划线。当禁用下划线的使用时，名称中包含下划线的请求头字段将被标记为无效，并受 ignore_invalid_headers 指令的影响。

如果在 server 级别指定此指令，则可以使用默认服务器的值。详细信息请参见“虚拟服务器选择”部分。

variables_hash_bucket_size 64;

设置变量哈希表的桶大小。关于设置哈希表的详细信息在单独的文档中提供。

variables_hash_max_size 1024;

设置变量哈希表的最大大小。关于设置哈希表的详细信息在单独的文档中提供。

在版本 1.5.13 之前，默认值是 512。

ngx_http_core_module 模块支持名称与 Apache 服务器变量匹配的嵌入式变量。首先，这些是表示客户端请求头字段的变量，例如 $http_user_agent、$http_cookie 等等。还有其他变量

$arg_name

请求行中的参数name

$args

请求行中的参数

$binary_remote_addr

客户端地址的二进制形式，IPv4 地址的值长度始终为 4 字节，IPv6 地址为 16 字节

$body_bytes_sent

发送给客户端的字节数，不包括响应头；此变量兼容 mod_log_config Apache 模块的“%B”参数

$bytes_sent

发送给客户端的字节数 (1.3.8, 1.2.5)

$connection

连接序号 (1.3.8, 1.2.5)

$connection_requests

通过连接完成的当前请求数 (1.3.8, 1.2.5)

$connection_time

连接时间，以秒为单位，分辨率到毫秒 (1.19.10)

$content_length

“Content-Length”请求头字段

$content_type

“Content-Type”请求头字段

$cookie_name

name cookie

$document_root

当前请求的 root 或 alias 指令的值

$document_uri

与 $uri 相同

$host

按此优先级顺序：来自请求行中的主机名，或来自“Host”请求头字段中的主机名，或与请求匹配的服务器名称

$hostname

主机名

$http_name

任意请求头字段；变量名称的最后部分是将字段名称转换为小写，并将破折号替换为下划线

$https

如果连接在 SSL 模式下运行则为“on”，否则为空字符串

$is_args

如果请求行有参数则为“?”，否则为空字符串

$limit_rate

设置此变量可启用响应速率限制；请参见 limit_rate

$msec

当前时间，以秒为单位，分辨率到毫秒 (1.3.9, 1.2.6)

$nginx_version

nginx 版本

$pid

工作进程的 PID

$pipe

如果请求是管道化的则为“p”，否则为“.” (1.3.12, 1.2.7)

$proxy_protocol_addr

来自 PROXY 协议头的客户端地址 (1.5.12)

PROXY 协议必须之前已启用，通过在 listen 指令中设置 proxy_protocol 参数。

$proxy_protocol_port

来自 PROXY 协议头的客户端端口 (1.11.0)

PROXY 协议必须之前已启用，通过在 listen 指令中设置 proxy_protocol 参数。

$proxy_protocol_server_addr

来自 PROXY 协议头的服务器地址 (1.17.6)

PROXY 协议必须之前已启用，通过在 listen 指令中设置 proxy_protocol 参数。

$proxy_protocol_server_port

来自 PROXY 协议头的服务器端口 (1.17.6)

PROXY 协议必须之前已启用，通过在 listen 指令中设置 proxy_protocol 参数。

$proxy_protocol_tlv_name

来自 PROXY 协议头的 TLV (1.23.2)。name 可以是 TLV 类型名称或其数值。在后一种情况下，值是十六进制的，应以 0x 为前缀

$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01

SSL TLV 也可以通过 TLV 类型名称或其数值访问，都以 ssl_ 为前缀

$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21

支持以下 TLV 类型名称

• alpn (0x01) - 连接使用的上层协议
• authority (0x02) - 客户端传递的主机名值
• unique_id (0x05) - 唯一连接 ID
• netns (0x30) - 命名空间的名称
• ssl (0x20) - 二进制 SSL TLV 结构

支持以下 SSL TLV 类型名称

• ssl_version (0x21) - 客户端连接中使用的 SSL 版本
• ssl_cn (0x22) - SSL 证书通用名称
• ssl_cipher (0x23) - 使用的密码名称
• ssl_sig_alg (0x24) - 用于签署证书的算法
• ssl_key_alg (0x25) - 公钥算法

此外，支持以下特殊 SSL TLV 类型名称

• ssl_verify - 客户端 SSL 证书验证结果，如果客户端提供了证书并成功验证则为 0，否则为非零值。

PROXY 协议必须之前已启用，通过在 listen 指令中设置 proxy_protocol 参数。

$query_string

与 $args 相同

$realpath_root

对应于当前请求的 root 或 alias 指令值的绝对路径名，所有符号链接已解析为实际路径

$remote_addr

客户端地址

$remote_port

客户端端口

$remote_user

使用基本认证提供的用户名

$request

完整的原始请求行

$request_body

请求体

该变量的值在请求体被读取到内存缓冲区后，可以在由proxy_pass、fastcgi_pass、uwsgi_pass和scgi_pass指令处理的locations中可用。

$request_body_file

包含请求体的临时文件的名称

处理结束时，需要移除该文件。要总是将请求体写入文件，需要启用client_body_in_file_only。当临时文件名称被传递给代理请求或FastCGI/uwsgi/SCGI服务器的请求时，应分别通过 proxy_pass_request_body off、 fastcgi_pass_request_body off、 uwsgi_pass_request_body off或 scgi_pass_request_body off指令禁用请求体的传递。

$request_completion

如果请求已完成，则为“OK”，否则为空字符串

$request_filename

当前请求的文件路径，基于root或alias指令和请求URI

$request_id

从16个随机字节生成的唯一请求标识符，采用十六进制表示 (1.11.0)

$request_length

请求长度（包括请求行、头部和请求体） (1.3.12, 1.2.7)

$request_method

请求方法，通常为“GET”或“POST”

$request_time

请求处理时间，单位为秒，精度为毫秒 (1.3.9, 1.2.6)；自客户端读取第一个字节以来经过的时间

$request_uri

完整的原始请求URI（带参数）

$scheme

请求方案，为“http”或“https”

$sent_http_name

任意响应头部字段；变量名的最后部分是将字段名转换为小写，并将破折号替换为下划线

$sent_trailer_name

在响应结束时发送的任意字段 (1.13.2)；变量名的最后部分是将字段名转换为小写，并将破折号替换为下划线

$server_addr

接受请求的服务器地址

计算此变量的值通常需要一次系统调用。为了避免系统调用，listen指令必须指定地址并使用bind参数。

$server_name

接受请求的服务器名称

$server_port

接受请求的服务器端口

$server_protocol

请求协议，通常为“HTTP/1.0”、“HTTP/1.1”、“HTTP/2.0”或“HTTP/3.0”

$status

响应状态 (1.3.2, 1.2.2)

$tcpinfo_rtt, $tcpinfo_rttvar, $tcpinfo_snd_cwnd, $tcpinfo_rcv_space

客户端TCP连接的信息；在支持TCP_INFO套接字选项的系统上可用

$time_iso8601

本地时间，ISO 8601标准格式 (1.3.12, 1.2.7)

$time_local

本地时间，Common Log Format格式 (1.3.12, 1.2.7)

$uri

请求中的当前URI，已规范化

$uri的值在请求处理过程中可能会改变，例如执行内部重定向或使用索引文件时。