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

读取和发送文件操作将被卸载到指定 pool 的线程中。如果省略了池名称，则使用名称为“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。

路径值可以包含变量，但不能包含$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 (请求实体过大) 错误。请注意，浏览器无法正确显示此错误。将 大小 设置为 0 将禁用对客户端请求体大小的检查。

connection_pool_size 256|512;

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

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

default_type text/plain;

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

directio off;

启用在读取大于或等于指定 大小 的文件时使用 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_requests 1000;

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

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

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

keepalive_time 1h;

限制了通过一个长连接处理请求的最大时间。达到此时间后，连接将在下一个请求处理后关闭。

keepalive_timeout 75s;

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

“Keep-Alive: timeout=时间”头字段被 Mozilla 和 Konqueror 所识别。MSIE 会在大约 60 秒后自行关闭保持活动状态的连接。

large_client_header_buffers 4 8k;

设置用于读取大客户端请求头的最大缓冲区的数目和大小。请求行的长度不能超过一个缓冲区的大小，否则将向客户端返回 414（请求 URI 过长）错误。请求头字段的长度也不能超过一个缓冲区的大小，否则将向客户端返回 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;
}

请注意，这将限制对除了 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连接，必须在服务器级别（1.19.1）指定该指令。

lingering_time 30s;

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

lingering_timeout 5s;

当lingering_close生效时，此指令指定等待更多客户端数据到达的最长时间。如果在此期间未接收到数据，连接将关闭。否则，数据将被读取并忽略，nginx重新等待更多数据。"等待-读取-忽略"的循环会重复，但不超过由lingering_time指令指定的时间。

listen *:80 | *:8000;

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

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;

如果只指定地址，则使用端口 80。

如果没有该指令，则如果 nginx 以超级用户特权运行，则使用*:80，否则使用*:8000。

如果存在default_server参数，则会导致服务器成为指定的地址:端口对的默认服务器。如果没有指令具有default_server参数，则该对的第一个服务器将成为该对的默认服务器。

在版本 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快速打开”功能（1.5.8版本），并限制尚未完成三次握手的连接队列的最大长度。

除非服务器能够处理接收带有数据的相同SYN数据包超过一次，否则不要启用此功能。

backlog=number

设置listen()调用中的backlog参数，限制挂起连接队列的最大长度。在FreeBSD、DragonFly BSD和macOS上，默认情况下，backlog设置为-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将只对*:port进行bind()。值得注意的是，在这种情况下，将进行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+ 上使用 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 进行的，在解码以“%XX”形式编码的文本、解析相对路径组件“.”和“..”引用以及可能的合并两个或更多相邻斜杠成一个斜杠之后。

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

location块可以嵌套，但下面有一些例外情况。

对于诸如macOS和Cygwin之类的不区分大小写的操作系统，使用前缀字符串进行匹配会忽略大小写（0.7.7）。但是，比较限于单字节区域设置。

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

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

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

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

让我们通过一个例子来说明上述问题：

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

log_not_found on;

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

log_subrequest off;

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

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

merge_slashes on;

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

请注意，压缩对于正确匹配前缀字符串和正则表达式位置是必要的。没有它，“//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参数配置期间内的文件访问的最小number，以保持文件描述符在缓存中保持打开状态。

open_file_cache_valid 60s;

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

output_buffers 2 32k;

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

在版本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 状态中，并填充缓冲区一段时间。

应该注意，超时的持久连接会被正常关闭。

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

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) 启用了在指定的 区域 中收集 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;

如果所有（all）或至少一个（any）ngx_http_access_module、ngx_http_auth_basic_module、ngx_http_auth_request_module或ngx_http_auth_jwt_module模块允许访问，则允许访问。

示例：

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 地址的（基于“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;

设置服务器名称哈希表的最大size。关于设置哈希表的详细信息，请参见单独的文档。

server_tokens on;

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

build参数（1.11.10）启用与nginx版本一起发出构建名称。

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

subrequest_output_buffer_size 4k|8k;

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

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

tcp_nodelay on;

启用或禁用 TCP_NODELAY 选项的使用。当连接转换为长连接状态时，该选项被启用。此外，它在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;
}

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

在 conf/mime.types 文件中，nginx 配备了一个足够完整的映射表。

要使特定位置对所有请求发出“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;

设置类型哈希表的最大 size。有关设置哈希表的详细信息，请参阅单独的 文档。

underscores_in_headers off;

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

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

variables_hash_bucket_size 64;

设置变量哈希表的桶大小。有关设置哈希表的详细信息，请参阅单独的 文档。

variables_hash_max_size 1024;

设置变量哈希表的最大 size。有关设置哈希表的详细信息，请参阅单独的 文档。

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

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

$arg_参数

请求行中的参数

$args

请求行中的参数

$binary_remote_addr

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

$body_bytes_sent

发送给客户端的字节数，不包括响应头；此变量与Apache模块mod_log_config的“%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_名称

名称 cookie

$document_root

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

$document_uri

与$uri相同

$host

优先顺序为：请求行中的主机名，或“Host”请求头字段中的主机名，或匹配请求的服务器名称

$hostname

主机名

$http_名称

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

$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）

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

$proxy_protocol_port

来自PROXY协议头的客户端端口（1.11.0）

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

$proxy_protocol_server_addr

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

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

$proxy_protocol_server_port

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

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

$proxy_protocol_tlv_name

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

$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01

SSL TLVs 也可以通过 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，否则为非零值。

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

$query_string

与 $args 相同

$realpath_root

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

$remote_addr

客户端地址

$remote_port

客户端端口

$remote_user

通过基本身份验证提供的用户名

$request

完整的原始请求行

$request_body

请求体

当请求体被读取到 内存缓冲区 时，变量的值在由 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

请求长度（包括请求行、头部和请求体）（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

通用日志格式中的本地时间（1.3.12，1.2.7）

$uri

请求中当前的URI，已标准化

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