模块 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 时，对于大于或等于 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 类型。可以使用 types 指令设置文件名扩展名到 MIME 类型的映射。

directio off;

当读取大于或等于指定大小的文件时，启用使用O_DIRECT标志（FreeBSD、Linux）、F_NOCACHE标志（macOS）或directio()函数。该指令自动禁用（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=部分

在检查符号链接（参数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”之外的所有方法）。

此外，可以使用“=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

off

响应始终被视为已修改（0.7.34）；

exact

精确匹配；

响应的修改时间小于或等于“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;

禁用与行为不当的浏览器的保持活动连接。browser 参数指定受影响的浏览器。值 msie6 在收到 POST 请求后禁用与旧版 MSIE 的保持活动连接。值 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=time”响应头字段中设置一个值。两个参数可能不同。

Mozilla 和 Konqueror 识别“Keep-Alive: timeout=time”头字段。MSIE 在大约 60 秒内自行关闭保持活动连接。

large_client_header_buffers 4 8k;

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

如果该指令在 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;

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

参数值可以包含变量 (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 的地址和端口，或 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 协议。

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

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 参数，该参数限制挂起连接队列的最大长度。默认情况下，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()调用。这很有用，因为如果有多个具有相同端口但不同地址的listen指令，并且其中一个listen指令侦听给定端口的所有地址（*:端口），nginx 将仅bind()到*:端口。应该注意，在这种情况下将进行getsockname()系统调用以确定接受连接的地址。如果使用了setfib、fastopen、backlog、rcvbuf、sndbuf、accept_filter、deferred、ipv6only、reuseport或so_keepalive参数，那么对于给定的地址:端口对，将始终进行单独的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），这些捕获稍后可用于其他指令中。

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

此外，使用“=”修饰符可以定义 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 编码的名称，则关闭压缩 off 可能变得必要，因为 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;
}

/data/w3/i/top.gif 文件将作为对“/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（基于 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;

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

build 参数 (1.11.10) 启用发出构建名称以及 nginx 版本。

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

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

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;

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

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 Server 变量匹配的嵌入变量。首先，这些是表示客户端请求头字段的变量，例如 $http_user_agent、$http_cookie 等。还有其他变量

$arg_name

请求行中的参数name

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

必须先在 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 协议标头中的 TLV（1.23.2）。name 可以是 TLV 类型名称或其数字值。在后一种情况下，该值是十六进制的，应以 0x 为前缀

$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01

还可以通过 TLV 类型名称或其数字值访问 SSL 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 的值可能会在请求处理期间发生变化，例如在执行内部重定向或使用索引文件时。