模块 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 上，从 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）读取和 发送 文件，而不会阻塞工作进程。

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 匹配指令值的最后一部分时

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 类型。可以使用 types 指令设置文件名扩展名到 MIME 类型的映射。

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

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

开启

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

如果不是所有者

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

from=部分

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

示例

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”之外的所有方法）。

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

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

精确

精确匹配；

之前

响应的修改时间小于或等于“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（内部服务器错误）。在这种情况下，可以在错误日志中看到“重写或内部重定向循环”消息。

keepalive_disable msie6;

禁用与行为异常的浏览器的保持活动连接。浏览器参数指定将受到影响的浏览器。值msie6禁用与旧版 MSIE 的保持活动连接，一旦收到 POST 请求。值safari禁用与 macOS 和类 macOS 操作系统上的 Safari 和类似 Safari 的浏览器的保持活动连接。值none启用与所有浏览器的保持活动连接。

在 1.1.18 版本之前，值safari匹配所有操作系统上的所有 Safari 和类似 Safari 的浏览器，并且默认情况下会禁用与它们的保持活动连接。

keepalive_requests 1000;

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

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

在 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 字节。如果在请求处理结束之后连接转换为保持活动状态，则这些缓冲区将被释放。

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

限制位置内允许的 HTTP 方法。方法参数可以是以下之一：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;

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

参数值可以包含变量（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 之前的版本中，它们只能在listen 指令中与default 参数一起指定。

setfib=number

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

fastopen=number

为侦听套接字启用“TCP 快速打开”（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

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

deferred

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

bind

指示对给定的address:port 对进行单独的bind() 调用。这很有用，因为如果有多个具有相同端口但地址不同的listen 指令，并且其中一个listen 指令侦听给定端口（*:port）上的所有地址，则 nginx 将只绑定到*: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+ 上使用SO_REUSEPORT_LB），允许内核在工作进程之间分配传入连接。这目前仅在 Linux 3.9+、DragonFly BSD 和 FreeBSD 12+（1.15.1）上有效。

不当使用此选项可能会对其安全 影响。

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

此参数（1.1.11）配置侦听套接字的“TCP 保活”行为。如果省略此参数，则操作系统设置将对套接字生效。如果将其设置为“on”值，则为套接字打开SO_KEEPALIVE 选项。如果将其设置为“off”值，则关闭套接字的SO_KEEPALIVE 选项。某些操作系统支持使用TCP_KEEPIDLE、TCP_KEEPINTVL 和TCP_KEEPCNT 套接字选项在每个套接字的基础上设置 TCP 保活参数。在这样的系统上（目前，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)，这些捕获稍后可以在其他指令中使用。

如果最长匹配前缀 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 参数配置的期间内，文件描述符保持在缓存中打开所需的最小文件访问次数 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 上，使用自 FreeBSD 9.0-CURRENT 起支持的 fcntl(O_READAHEAD, size) 系统调用。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) 启用在指定的 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 模块中的所有 (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”响应头字段的值可以使用带有变量的 字符串 显式设置。空字符串禁用“Server”字段的发出。

subrequest_output_buffer_size 4k|8k;

设置用于存储子请求响应体的缓冲区 大小。默认情况下，缓冲区大小等于一个内存页面。这可能是 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 指令从 文件 参数构造。可以通过在名称末尾指定斜杠来检查目录是否存在，例如“$uri/”。如果未找到任何文件，则会内部重定向到最后一个参数中指定的 URI。例如

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

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

最后一个参数也可以指向命名位置，如下面的示例所示。从 0.7.51 版本开始，最后一个参数也可以是 代码

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 文件中分发了足够完整的映射表。

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

请求行中的参数 名称

$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_名称

名称 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_名称

来自 PROXY 协议头的 TLV（1.23.2）。名称 可以是 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，否则为非零值。

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

$query_string

与 $args 相同

$realpath_root

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

$remote_addr

客户端地址

远程端口

客户端端口

远程用户

使用 Basic 认证提供的用户名

请求行

完整的原始请求行

请求体

请求体

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

请求体文件

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

在处理结束时，需要删除该文件。要始终将请求体写入文件，需要启用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指令禁用传递请求体。

请求完成状态

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

请求文件名

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

请求ID

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

请求长度

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

请求方法

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

请求时间

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

请求URI

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

方案

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

$sent_http_name

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

$sent_trailer_name

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

服务器地址

接受请求的服务器的地址

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

服务器名称

接受请求的服务器的名称

服务器端口

接受请求的服务器的端口

服务器协议

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

状态码

响应状态 (1.3.2, 1.2.2)

$tcpinfo_rtt、$tcpinfo_rttvar、$tcpinfo_snd_cwnd、$tcpinfo_rcv_space

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

ISO 8601时间

以 ISO 8601 标准格式表示的本地时间 (1.3.12, 1.2.7)

本地时间

以通用日志格式表示的本地时间 (1.3.12, 1.2.7)

URI

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

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