Module ngx_http_core_module

• Directives
  • absolute_redirect
  • aio
  • aio_write
  • alias
  • auth_delay
  • chunked_transfer_encoding
  • client_body_buffer_size
  • client_body_in_file_only
  • client_body_in_single_buffer
  • client_body_temp_path
  • client_body_timeout
  • client_header_buffer_size
  • client_header_timeout
  • client_max_body_size
  • connection_pool_size
  • default_type
  • directio
  • directio_alignment
  • disable_symlinks
  • error_page
  • etag
  • http
  • if_modified_since
  • ignore_invalid_headers
  • internal
  • keepalive_disable
  • keepalive_requests
  • keepalive_timeout
  • large_client_header_buffers
  • limit_except
  • limit_rate
  • limit_rate_after
  • lingering_close
  • lingering_time
  • lingering_timeout
  • listen
  • location
  • log_not_found
  • log_subrequest
  • max_ranges
  • merge_slashes
  • msie_padding
  • msie_refresh
  • open_file_cache
  • open_file_cache_errors
  • open_file_cache_min_uses
  • open_file_cache_valid
  • output_buffers
  • port_in_redirect
  • postpone_output
  • read_ahead
  • recursive_error_pages
  • request_pool_size
  • reset_timedout_connection
  • resolver
  • resolver_timeout
  • root
  • satisfy
  • send_lowat
  • send_timeout
  • sendfile
  • sendfile_max_chunk
  • server
  • server_name
  • server_name_in_redirect
  • server_names_hash_bucket_size
  • server_names_hash_max_size
  • server_tokens
  • subrequest_output_buffer_size
  • tcp_nodelay
  • tcp_nopush
  • try_files
  • types
  • types_hash_bucket_size
  • types_hash_max_size
  • underscores_in_headers
  • variables_hash_bucket_size
  • variables_hash_max_size
• Embedded Variables
  

Directives

该指令出现在 1.11.8 版本中。

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

另请参见server_name_in_redirect和port_in_redirect指令。

该指令出现在版本 0.8.11 中。

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

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

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

options VFS_AIO

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

kldload aio

在 Linux 上，可以从内核版本 2.6.22 开始使用 AIO。另外，有必要启用directio，否则将阻止读取：

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

在 Linux 上，directio仅可用于读取在 512 字节边界(对于 XFS 为 4K)上对齐的块。在阻塞模式下读取文件未对齐的结尾。对于字节范围请求和 FLV 请求(并非从文件开头开始)也是如此：在文件的开头和结尾读取未对齐的数据将被阻止。

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

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

最后，可以使用多线程(1.7.11)读取文件和sent，而不会阻塞辅助进程：

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

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

aio threads=pool$disk;

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

另请参见sendfile指令。

该指令出现在 1.9.13 版中。

如果启用了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 与指令值的最后一部分匹配时：

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

最好改用root指令：

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

该指令出现在版本 1.17.10 中。

当访问受password，子请求的结果或JWT限制时，使用 401 响应代码延迟对未授权请求的处理，以防止定时攻击。

允许在 HTTP/1.1 中禁用分块传输编码。当使用尽管标准有要求而仍不支持分块编码的软件时，它可能会派上用场。

设置用于读取客户端请求正文的缓冲区大小。如果请求主体大于缓冲区，则将整个主体或仅将其一部分写入temporary file。默认情况下，缓冲区大小等于两个内存页。在 x86，其他 32 位平台和 x86-64 上为 8K。在其他 64 位平台上，通常为 16K。

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

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

值clean将导致删除请求处理后剩余的临时文件。

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

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

client_body_temp_path /spool/nginx/client_temp 1 2;

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

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

定义读取客户端请求正文的超时。仅在两次连续读取操作之间的一段时间内设置超时，而不是为整个请求主体的传输设置超时。如果客户端在此时间内未传输任何内容，则请求将终止并显示 408(请求超时)错误。

设置用于读取客户端请求 Headers 的缓冲区大小。对于大多数请求，一个 1K 字节的缓冲区就足够了。但是，如果请求中包含长 Cookie 或来自 WAP 客户端，则该请求可能不适合 1K。如果请求行或请求 Headers 字段不适合此缓冲区，则将分配由large_client_header_buffers指令配置的较大缓冲区。

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

设置客户端请求正文的最大允许大小，在“ Content-Length”请求 Headers 字段中指定。如果请求中的大小超过配置的值，则会向客户端返回 413(请求实体太大)错误。请注意，浏览器无法正确显示此错误。将size设置为 0 将禁用客户端请求主体大小的检查。

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

定义响应的默认 MIME 类型。可以使用types指令设置文件 extensions 到 MIME 类型的映射。

该指令出现在版本 0.7.7 中。

当读取大于或等于指定的size的文件时，启用O_DIRECT标志(FreeBSD，Linux)，F_NOCACHE标志(macOS)或directio()函数(Solaris)的使用。该指令自动针对给定请求禁用(0.7.15)sendfile的使用。它对于提供大文件很有用：

directio 4m;

或在 Linux 上使用aio时。

该指令出现在版本 0.8.11 中。

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

该指令出现在 1.1.15 版中。

确定打开文件时应如何对待符号链接：

• off

  • 路径名中的符号链接是允许的，而不是选中的。这是默认行为。

• on

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

• if_not_owner

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

• from = part

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

Example:

disable_symlinks on from=$document_root;

该伪指令仅在具有openat()和fstatat()接口的系统上可用。这样的系统包括 FreeBSD，Linux 和 Solaris 的现代版本。

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

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

Example:

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;
}

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

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

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

当且仅当当前级别上没有定义error_page指令时，这些指令才从上一级继承。

该指令出现在版本 1.3.3 中。

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

提供在其中指定 HTTP 服务器指令的配置文件上下文。

该指令出现在版本 0.7.24 中。

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

• off

  • “ If-Modified-Since”请求 Headers 字段被忽略(0.7.34)；

• exact

  • exact match;

• before

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

控制是否应忽略名称无效的标题字段。有效名称由英文字母，数字，连字符和可能的下划线组成(由underscores_in_headers指令控制)。

如果指令是在server级别上指定的，则仅当服务器为默认服务器时才使用其值。指定的值也适用于在相同地址和端口上侦听的所有虚拟服务器。

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

• 通过error_page，index，random_index和try_files指令重定向的请求；

• 由上游服务器通过“ X-Accel-Redirect”响应头字段重定向的请求；

• 由ngx_http_ssi_module模块的“ include virtual”命令，ngx_http_addition_module模块指令以及auth_request和mirror指令形成的子请求；

• rewrite指令更改了请求。

Example:

error_page 404 /404.html;

location = /404.html {
    internal;
}

禁用行为异常的浏览器的保持活动连接。 browser参数指定将影响哪些浏览器。收到 POST 请求后，值msie6将禁用与旧版本 MSIE 的保持活动连接。值safari禁用与 macOS 和类似 macOS 的 os 上的 Safari 和类似 Safari 的浏览器保持活动连接。值none启用与所有浏览器的保持活动连接。

该指令出现在版本 0.8.0 中。

设置可以通过一个保持活动连接服务的最大请求数。发出最大数量的请求后，将关闭连接。

要释放每个连接的内存分配，必须定期关闭连接。因此，使用过多的最大请求数可能会导致过多的内存使用，因此不建议这样做。

第一个参数设置超时，在此期间，保持活动的客户端连接将在服务器端保持打开状态。零值将禁用保持活动状态的客户端连接。可选的第二个参数在“ Keep-Alive：timeout = time”响应 Headers 字段中设置一个值。两个参数可能不同。

Mozilla 和 Konqueror 可以识别“ Keep-Alive：timeout = time”标题字段。 MSIE 会在大约 60 秒内自行关闭保持活动的连接。

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

限制位置内允许的 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;
}

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

限制向客户端传输响应的速率。 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”Headers 字段中设置。可以使用proxy_ignore_headers，fastcgi_ignore_headers，uwsgi_ignore_headers和scgi_ignore_headers指令禁用此功能。

该指令出现在版本 0.8.0 中。

设置初始数量，之后将进一步限制对客户端的响应的进一步传输。参数值可以包含变量(1.17.0)。

Example:

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

该指令出现在 1.1.0 和 1.0.6 版本中。

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

默认值“ on”指示 nginx 在完全关闭连接之前从客户端发送wait for和process附加数据，但前提是启发式建议客户端可能发送更多数据。

值“ always”将使 nginx 无条件 await 并处理其他客户端数据。

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

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

lingering_close有效时，此指令指定 nginx 处理(读取和忽略)来自客户端的其他数据的最长时间。之后，即使有更多数据，连接也会关闭。

lingering_close有效时，此伪指令指定更多客户端数据到达的最大 await 时间。如果在此期间未接收到数据，则连接将关闭。否则，将读取并忽略数据，并且 nginx 开始再次 await 更多数据。重复“ wait-read-ignore”循环，但不超过lingering_time指令指定的时间。

为 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对的第一台服务器将是该对的默认服务器。

ssl参数(0.7.14)允许指定此端口上接受的所有连接均应以 SSL 模式工作。这样可以为处理 HTTP 和 HTTPS 请求的服务器提供更紧凑的configuration。

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

spdy参数(1.3.15-1.9.4)允许在此端口上接受SPDY连接。通常，为了使其正常工作，还应指定ssl参数，但是也可以将 nginx 配置为接受不带 SSL 的 SPDY 连接。

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

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

• setfib = number

  • 此参数(0.8.44)设置侦听套接字的关联路由表 FIB(SO_SETFIB选项)。目前这仅适用于 FreeBSD。

• fastopen = number

  • 为侦听套接字(1.5.8)启用“ TCP 快速打开”，为尚未完成三向握手的连接队列启用limits的最大长度。

• 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，backlog，rcvbuf，sndbuf，accept_filter，deferred，ipv6only或so_keepalive参数，则对于给定的address：port对，将始终进行单独的bind()调用。

• ipv6only = on | off

  • 此参数(0.7.42)(通过IPV6_V6ONLY套接字选项)确定在通配符地址[::]上侦听的 IPv6 套接字是否仅接受 IPv6 连接还是接受 IPv6 和 IPv4 连接。默认情况下，此参数是打开的。启动时只能设置一次。

reuseport

• 此参数(1.9.1)指示为每个工作进程创建一个单独的侦听套接字(在 Linux 3.9 和 DragonFly BSD 上使用SO_REUSEPORT socket 选项，在 FreeBSD 12 上使用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”行为。如果省略此参数，则 os 的设置对套接字有效。如果将其设置为值“ on”，则将为套接字打开SO_KEEPALIVE选项。如果将其设置为值“ off”，则套接字的SO_KEEPALIVE选项将关闭。某些 os 使用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 个探测。

Example:

listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

根据请求 URI 设置配置。

在对以“ %XX”形式编码的文本进行解码，将对相对路径分量“ .”和“ ..”以及两个或多个相邻斜杠的可能compression的引用解析为单个斜杠之后，针对标准化 URI 执行匹配。

位置可以由前缀字符串或正则表达式定义。正则表达式由前面的“ ~*”修饰符(不区分大小写的匹配)或“ ~”修饰符(不区分大小写的匹配)指定。为了找到与给定请求匹配的位置，nginx 首先检查使用前缀字符串定义的位置(前缀位置)。其中，选择并记住具有最长匹配前缀的位置。然后按照在配置文件中出现的顺序检查正则表达式。正则表达式的搜索在第一个匹配项上终止，并使用相应的配置。如果未找到与正则表达式匹配的内容，则使用前面记住的前缀位置的配置。

可以嵌套location个块，下面会提到一些 exception。

对于不区分大小写的 os，例如 macOS 和 Cygwin，与前缀字符串匹配将忽略大小写(0.7.7)。但是，比较仅限于一字节的语言环境。

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

如果最长的匹配前缀位置具有“ ^~”修饰符，则不检查正则表达式。

同样，使用“ =”修饰符可以定义 URI 和位置的精确匹配。如果找到完全匹配的内容，搜索将终止。例如，如果“ /”请求频繁发生，则定义“ 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 相匹配。 。

“ @”前缀定义命名位置。这样的位置不用于常规请求处理，而是用于请求重定向。它们不能嵌套，也不能包含嵌套位置。

如果位置由以斜杠字符结尾的前缀字符串定义，并且请求由proxy_pass，fastcgi_pass，uwsgi_pass，scgi_pass，memcached_pass或grpc_pass之一处理，则将执行特殊处理。响应 URI 等于此字符串但不带斜杠的请求，带有代码 301 的永久重定向将返回到请求的 URI，并附加斜杠。如果不希望这样，则可以这样定义 URI 和位置的完全匹配：

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

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

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

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

该指令出现在版本 1.1.2 中。

限制字节范围请求中允许的最大范围数。超出限制的请求将被视为没有指定字节范围。默认情况下，范围数不受限制。零值将完全禁用字节范围支持。

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

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

location /scripts/ {
    ...
}

并且可能会作为静态文件处理。因此将其转换为“ /scripts/one.php”。

如果 URI 包含 base64 编码的名称，则有必要将压缩off设为必需，因为 base64 在内部使用“ /”字符。但是，出于安全考虑，最好避免关闭压缩。

如果指令是在server级别上指定的，则仅当服务器为默认服务器时才使用其值。指定的值也适用于在相同地址和端口上侦听的所有虚拟服务器。

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

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

配置可以存储以下内容的缓存：

• 打开文件 Descriptors，它们的大小和修改时间；

• 有关目录存在的信息；

• 文件查找错误，例如“找不到文件”，“没有读取权限”等。

该指令具有以下参数：

• max

  • 设置缓存中元素的最大数量；在高速缓存溢出时，将删除最近最少使用(LRU)元素；

• inactive

  • 定义一个时间，如果在这段时间内没有访问过元素，则从缓存中删除该元素；默认为 60 秒；

• off

  • 禁用缓存。

Example:

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缓存文件查找错误。

设置在open_file_cache指令的inactive参数配置的时间段内文件访问的最小number，文件 Descriptors 在高速缓存中保持打开状态所需。

设置一个时间，之后应验证open_file_cache个元素。

设置用于从磁盘读取响应的缓冲区的number和size。

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

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

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

设置使用文件时内核的预读量。

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

在 FreeBSD 上，使用了从 FreeBSD 9.0-CURRENT 开始受支持的fcntl(O_READAHEAD, size )系统调用。 FreeBSD 7 必须为patched。

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

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

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

应该注意的是，超时的保持活动连接通常是关闭的。

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

resolver 127.0.0.1 [::1]:5353;

可以使用可选端口(1.3.1，1.2.2)将地址指定为域名或 IP 地址。如果未指定端口，则使用端口 53.以循环方式查询名称服务器。

默认情况下，nginx 在解析时将同时查找 IPv4 和 IPv6 地址。如果不需要查找 IPv6 地址，则可以指定ipv6=off参数。

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

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

可选的status_zone参数(1.17.1)启用collection的 DNS 服务器统计信息，用于指定zone中的请求和响应。该参数可作为commercial subscription的一部分使用。

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

resolver_timeout 5s;

设置请求的根目录。例如，使用以下配置

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

/data/w3/i/top.gif文件将作为对“ /i/top.gif”请求的响应而发送。

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

只需将 URI 添加到root指令的值即可构造文件的路径。如果必须修改 URI，则应使用alias指令。

如果ngx_http_access_module，ngx_http_auth_basic_module，ngx_http_auth_request_module或ngx_http_auth_jwt_module模块的全部(all)或至少一个(any)允许访问，则允许访问。

Example:

location / {
    satisfy any;

    allow 192.168.1.0/32;
    deny  all;

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

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

在 Linux，Solaris 和 Windows 上，此伪指令将被忽略。

设置将响应传输到客户端的超时时间。超时仅在两个连续的写操作之间设置，而不用于整个响应的传输。如果客户端在此时间内未收到任何信息，则连接将关闭。

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

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

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

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

设置为非零值时，将限制单个sendfile()调用中可以传输的数据量。没有限制，一个快速连接可能会完全占用工作进程。

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

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

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 "";
}

它允许该服务器处理给定 address：port 对的不带“ Host”头域的请求，而不是默认服务器。这是默认设置。

在按名称搜索虚拟服务器的过程中，如果名称与多个指定的变体匹配(例如，通配符名称和正则表达式匹配)，则将按照以下优先级顺序选择第一个匹配的变体：

• 确切的名字

• 以星号开头的最长通配符名称，例如“ *.example.com”

• 以星号结尾的最长通配符名称，例如“ mail.*”

• 第一个匹配的正则表达式(按在配置文件中出现的顺序)

服务器名称的详细说明在单独的Server names文档中提供。

在 ng 发出的absolute重定向中启用或禁用server_name指令指定的主服务器名称。禁止使用主服务器名称时，将使用“主机”请求 Headers 字段中的名称。如果不存在此字段，则使用服务器的 IP 地址。

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

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

设置服务器名称哈希表的最大size。设置哈希表的详细信息在单独的document中提供。

在错误页面和“服务器”响应标题字段中启用或禁用运行 Nginx 版本。

build参数(1.11.10)可以与 nginx 版本一起发出build name。

此外，作为commercial subscription的一部分，从 1.9.13 版本开始，可以使用带有变量的string显式设置错误页面上的签名和“服务器”响应 Headers 字段值。空字符串将禁用“服务器”字段的运行。

该指令出现在版本 1.13.10 中。

设置用于存储子请求的响应主体的缓冲区的size。默认情况下，缓冲区大小等于一个内存页。根据平台的不同，它可以是 4K 或 8K。但是，它可以做得更小。

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

启用或禁用TCP_NODELAY选项的使用。当连接转换为保持活动状态时，将启用该选项。此外，它在 SSL 连接，无缓冲代理和WebSocket代理中启用。

在 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;
}

最后一个参数也可以指向一个命名的位置，如下面的示例所示。从版本 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;
}

And here,

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
}

将文件 extensions 映射到响应的 MIME 类型。extensions 不区分大小写。几个 extensions 可以映射为一种类型，例如：

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

在conf/mime.types文件中使用 nginx 分发了足够完整的映射表。

要使特定位置为所有请求发出“ application/octet-stream” MIME 类型，可以使用以下配置：

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

设置类型哈希表的存储桶大小。设置哈希表的详细信息在单独的document中提供。

设置类型哈希表的最大size。设置哈希表的详细信息在单独的document中提供。

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

如果指令是在server级别上指定的，则仅当服务器为默认服务器时才使用其值。指定的值也适用于在相同地址和端口上侦听的所有虚拟服务器。

设置变量哈希表的存储桶大小。设置哈希表的详细信息在单独的document中提供。

设置变量哈希表的最大值size。设置哈希表的详细信息在单独的document中提供。

Embedded Variables

ngx_http_core_module模块支持名称与 Apache Server 变量匹配的嵌入式变量。首先，这些是代表客户端请求 Headers 字段的变量，例如$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)

$content_length

• “内容长度”请求 Headers 字段

$content_type

• “Content Type”请求 Headers 字段

$cookie_ name

• name cookie

$document_root

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

$document_uri

• 与$uri相同

$host

• 优先顺序如下：请求行中的主机名，或“主机”请求 Headers 字段中的主机名，或与请求匹配的服务器名

$hostname

• host name

$http_ name

• 任意请求头字段；变量名称的最后一部分是将字段名称转换为小写字母，并用短划线代替下划线

$https

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

$is_args

• “ ?”(如果请求行包含参数)，否则为空字符串

$limit_rate

• 设置此变量将启用响应率限制；见limit_rate

$msec

• 以毫秒为单位的当前时间(以秒为单位)(1.3.9，1.2.6)

$nginx_version

• nginx version

$pid

• 工作进程的 PID

$pipe

• 如果请求已通过管道传递，则为“ p”，否则为“ .”(1.3.12、1.2.7)

$proxy_protocol_addr

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

必须先通过在listen指令中设置proxy_protocol参数来启用 PROXY 协议。

$proxy_protocol_port

• PROXY 协议 Headers(1.11.0)中的客户端端口

必须先通过在listen指令中设置proxy_protocol参数来启用 PROXY 协议。

$proxy_protocol_server_addr

• PROXY 协议 Headers 中的服务器地址(1.17.6)

必须先通过在listen指令中设置proxy_protocol参数来启用 PROXY 协议。

$proxy_protocol_server_port

• PROXY 协议 Headers 中的服务器端口(1.17.6)

必须先通过在listen指令中设置proxy_protocol参数来启用 PROXY 协议。

$query_string

• 与$args相同

$realpath_root

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

$remote_addr

• client address

$remote_port

• client port

$remote_user

• 基本身份验证随附的用户名

$request

• 完整的原始请求行

$request_body

• request body

当将请求正文读取到memory buffer时，该变量的值可在proxy_pass，fastcgi_pass，uwsgi_pass和scgi_pass指令处理的位置使用。

$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

• 请求长度(包括请求行，Headers 和请求正文)(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”

$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

• 通用日志格式的本地时间(1.3.12，1.2.7)

$uri

• 请求中的当前 URI，normalized

$uri的值可能会在请求处理期间更改，例如在进行内部重定向或使用索引文件时。