模块 ngx_http_core_module

absolute_redirect on;

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

另请参见 server_name_in_redirect 和 port_in_redirect Directives。

aio off;

启用或禁用异步文件 I/O （AIO） 的使用 在 FreeBSD 和 Linux 上：

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 请求也是如此 not 从文件的开头开始：在 文件的开头和结尾将被阻塞。

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

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

最后，可以使用多线程 （1.7.11） 读取和发送文件， 而不阻止 worker 进程：

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

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

aio threads=pool$disk;

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

另请参见 sendfile Directives。

aio_write off;

如果开启 aio，则选择是否用于写入文件。 目前，这仅在使用时有效，并且仅限于编写临时文件 以及从代理服务器接收的数据。aio threads

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

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

应要求 “”，则会发送文件。/i/top.gif/data/w3/images/top.gif

该值可以包含变量、 except 和 .path$document_root$realpath_root

If 在定义的位置内使用 替换为正则表达式，则此类正则表达式应 包含捕获，并应引用 这些捕获 （0.7.40），例如：aliasalias

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

当 location 与Directives值的最后一部分匹配时：

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

最好改用 root Directives：

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

auth_delay 0s;

使用 401 响应代码延迟处理未经授权的请求 为了防止在访问受密码限制时进行计时攻击，通过 subrequest 的结果， 或通过 JWT 获取。

chunked_transfer_encoding on;

允许在 HTTP/1.1 中禁用分块传输编码。 当使用不支持的软件时，它可能会派上用场 chunked encoding 的 Imported 编码。

client_body_buffer_size 8k|16k;

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

client_body_in_file_only off;

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

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

该值将导致临时文件 left after request processing 被删除。clean

client_body_in_single_buffer off;

确定 nginx 是否应保存整个客户端请求正文 在单个缓冲区中。 使用变量时，建议使用该Directives，以节省所涉及的复制作数。$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 Directives 被分配。

如果在服务器级别指定了该Directives，则 可以使用 default server 中的值。 有关详细信息，请参阅 “虚拟 server selection“部分。

client_header_timeout 60s;

定义读取客户端请求标头的超时。 如果客户端在此时间内没有传输整个标头，则 请求终止，并显示 408 （请求超时） 错误。

client_max_body_size 1m;

设置客户端请求正文允许的最大大小。 如果请求中的大小超过配置的值，则 413（请求实体太大） 错误返回给客户端。 请注意 浏览器无法正确显示 这个错误。 设置为 0 将禁用客户端检查 请求正文大小。size

connection_pool_size 256|512;

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

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

default_type text/plain;

定义响应的默认 MIME 类型。 可以设置文件扩展名到 MIME 类型的映射 替换为 types Directives。

directio off;

允许使用 标志 （FreeBSD， Linux）， 标志 （macOS）、 或函数 （Solaris）、 读取大于或等于 指定的 . 该Directives自动禁用 （0.7.15） 对给定请求使用 sendfile。 它对于提供大文件很有用：O_DIRECTF_NOCACHEdirectio()size

directio 4m;

或在 Linux 上使用 aio 时。

directio_alignment 512;

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

disable_symlinks off;

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

off

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

on

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

if_not_owner

如果路径名的任何组件 是一个符号链接，而链接 指向具有不同的所有者。

from=part

检查符号链接时 （parameters 和 ）、 通常会检查 pathname 的所有组件。 检查路径名开头部分的符号链接 可以通过额外指定 = 参数来避免。 在这种情况下，仅从 位于指定初始部分后面的 pathname 组件。 如果该值不是选中的路径名的初始部分，则整个 pathname 的检查方式，就好像根本没有指定这个参数一样。 如果该值与整个文件名匹配，则 不检查符号链接。 参数值可以包含变量。onif_not_ownerfrompart

例：

disable_symlinks on from=$document_root;

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

Parameters 并添加处理开销。onif_not_owner

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

ngx_http_autoindex_module、ngx_http_random_index_module、 和 ngx_http_dav_module 模块当前忽略此Directives。

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

例：

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

这会导致internal重定向到指定的 客户端请求方法更改为 “” （对于除 “” 和 “”）。uriGETGETHEAD

此外，还可以将响应代码更改为另一个 使用 “” 语法，例如：=response

error_page 404 =200 /empty.gif;

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

error_page 404 = /404.php;

如果在internal重定向期间不需要更改 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）。

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

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

这些Directives继承自之前的配置级别 当且仅当没有Directives时 在当前级别上定义。error_page

etag on;

启用或禁用自动生成 “ETag” static 资源的 response header 字段。

提供配置文件上下文，其中 HTTP 服务器Directives 指定。

if_modified_since exact;

指定如何比较响应的修改时间 随着时间在 “如果-修改-since” 请求标头字段：

off

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

exact

完全匹配;

before

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

ignore_invalid_headers on;

控制是否应忽略名称无效的标题字段。 有效名称由英文字母、数字、连字符和可能的 下划线（由 underscores_in_headers Directives控制）。

如果在服务器级别指定了该Directives，则 可以使用 default server 中的值。 有关详细信息，请参阅 “虚拟 server selection“部分。

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

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

例：

error_page 404 /404.html;

location = /404.html {
    internal;
}

每个请求最多只能阻止 10 个internal重定向 请求处理周期。 如果达到此限制，则会出现错误 返回 500 （Internal Server Error）。 在这种情况下，“rewrite or internal redirection cycle” 消息 可以在错误日志中看到。

keepalive_disable msie6;

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

在版本 1.1.18 之前，值匹配 所有作系统上的所有 Safari 和类似 Safari 的浏览器，以及 默认情况下，与它们的 keep-alive 连接处于禁用状态。safari

keepalive_requests 1000;

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

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

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

keepalive_time 1h;

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

keepalive_timeout 75s;

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

这 “保持连接状态：超时=” header 字段被 Mozilla 和 Konqueror 识别。 MSIE 在大约 60 秒内自行关闭 keep-alive 连接。time

large_client_header_buffers 4 8k;

设置最大值 和 用于读取大型客户端请求标头的缓冲区。 请求行不能超过一个缓冲区的大小，或者 414 （请求 URI 太大） 错误返回给客户端。 请求标头字段也不能超过一个缓冲区的大小，或者 400 （错误请求） 错误返回给客户端。 缓冲区仅按需分配。 默认情况下，缓冲区大小等于 8K 字节。 如果在请求处理结束后，连接被转换 进入 keep-alive 状态时，这些缓冲区将被释放。numbersize

如果在服务器级别指定了该Directives，则 可以使用 default server 中的值。 有关详细信息，请参阅 “虚拟 server selection“部分。

限制一个位置内允许的 HTTP 方法。 参数可以是以下值之一： ， ， ， 或。 允许该方法将使该方法也被允许。 可以使用 ngx_http_access_module、 ngx_http_auth_basic_module、 和 ngx_http_auth_jwt_module （1.13.10） modules Directives：methodGETHEADPOSTPUTDELETEMKCOLCOPYMOVEOPTIONSPROPFINDPROPPATCHLOCKUNLOCKPATCHGETHEAD

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

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

limit_rate 0;

限制向客户端传输响应的速率。 以每秒字节数为单位指定。 零值将禁用速率限制。 限制是按请求设置的，因此，如果客户端同时打开 两个连接，则总体速率将是 2 倍 指定为指定的限制。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 Directives。

limit_rate_after 0;

设置初始量，之后进一步传输 的响应将受到速率限制。 参数值可以包含变量 （1.17.0）。

例：

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

lingering_close on;

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

默认值 “” 指示 nginx 等待并处理来自客户端的其他数据 在完全关闭连接之前，但仅限于 如果启发式建议客户端可能正在发送更多数据。on

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

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

要控制关闭 HTTP/2 连接， 该Directives必须在服务器级别 （1.19.1） 上指定。

lingering_time 30s;

当 lingering_close 生效时， 该Directives指定 nginx 将处理 （读取和忽略） 来自客户端的其他数据。 之后，连接将被关闭，即使会有 更多数据。

lingering_timeout 5s;

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

listen *:80 | *:8000;

设置 IP 的 和 或者 UNIX 域套接字的 服务器将接受请求。 和 ， 或 only 或 only 可以指定。 也可以是主机名，例如：addressportpathaddressportaddressportaddress

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。address

如果该Directives不存在，则使用 nginx 是否以超级用户权限运行，否则。*:80*:8000

参数（如果存在） 将导致服务器成为指定 ： 对的默认服务器。 如果没有任何Directives具有参数，则第一个具有 ： 对的服务器将为 此对的默认服务器。default_serveraddressportdefault_serveraddressport

在 0.8.21 之前的版本中，此参数被简单地命名为 。default

参数 （0.7.14） 允许指定所有 此端口接受的连接应在 SSL 模式下工作。 这允许对服务器进行更紧凑的配置，该 处理 HTTP 和 HTTPS 请求。ssl

参数 （1.9.5） 将端口配置为接受 HTTP/2 连接。 通常，要使其正常工作，参数应为 ，但 nginx 也可以配置为接受 HTTP/2 没有 SSL 的连接。http2ssl

该参数已弃用， http2 Directives 应该改用。

参数 （1.25.0） 将端口配置为接受 QUIC 连接。quic

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

从版本 1.13.11 开始支持 PROXY 协议版本 2。

Directives 可以具有几个特定于 socket 相关系统调用的附加参数。 这些参数可以在任何Directives中指定，但只能为给定的 ： 对指定一次。listenlistenaddressport

在 0.8.21 之前的版本中，它们只能是 在Directives中与参数一起指定。listendefault

setfib=number

此参数 （0.8.44） 设置关联的路由表 FIB （该选项）用于侦听套接字。 这目前只适用于 FreeBSD。SO_SETFIB

fastopen=number

使 TCP 快速打开 对于侦听套接字 （1.5.8），并限制尚未完成的连接队列的最大长度 三次握手。

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

backlog=number

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

rcvbuf=size

设置接收缓冲区大小 （该选项）用于侦听套接字。SO_RCVBUF

sndbuf=size

设置发送缓冲区大小 （该选项）用于侦听套接字。SO_SNDBUF

accept_filter=filter

设置 Accept 过滤器的名称 （选项）用于侦听套接字 ，在将传入连接传递给 之前对其进行筛选。 这仅适用于 FreeBSD 和 NetBSD 5.0+。 可能的值为 dataready 和 httpready。SO_ACCEPTFILTERaccept()

deferred

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

bind

指示对给定的 ： 对进行单独调用。 这很有用，因为如果有多个 port 相同但地址不同的 directive，并且其中一个 directive 侦听所有地址 对于给定的端口 （），nginx 将只到 。 应该注意的是，系统调用将是 用于确定接受连接的地址。 如果 、 、 、 或 parameters 则用于给定的 ： 对 将始终进行单独的调用。bind()addressportlistenlisten*:portbind()*:portgetsockname()setfibfastopenbacklogrcvbufsndbufaccept_filterdeferredipv6onlyreuseportso_keepaliveaddressportbind()

ipv6only=on|off

此参数 （0.7.42） 确定 （通过 socket 选项） 侦听通配符地址的 IPv6 套接字是只接受 IPv6 连接，还是同时接受 IPv6 和 IPv4 连接。 默认情况下，此参数处于打开状态。 它只能在启动时设置一次。IPV6_V6ONLY[::]

在 1.3.4 版本之前， 如果省略此参数，则作系统的设置为 对 socket 有效。

reuseport

此参数 （1.9.1） 指示创建单独的侦听套接字 对于每个工作进程 （在 Linux 3.9+ 和 DragonFly BSD 上使用 socket 选项， 或在 FreeBSD 12+ 上），允许内核 在 worker 进程之间分配传入连接。 这目前仅适用于 Linux 3.9+、DragonFly BSD、 和 FreeBSD 12+ （1.15.1）。SO_REUSEPORTSO_REUSEPORT_LB

不恰当地使用此选项可能会产生其安全隐患。

so_keepalive=on||[]:[]:[offkeepidlekeepintvlkeepcnt]

此参数 （1.1.11） 配置 “TCP keepalive” 行为 用于侦听套接字。 如果省略此参数，则作系统的设置将为 对 socket 有效。 如果它设置为值 “”，则为套接字打开该选项。 如果它设置为值 “”，则关闭套接字的选项。 某些作系统支持在 使用 、 和 socket 选项的 per-socket 基础。 在此类系统上（目前为 Linux 2.4+、NetBSD 5+ 和 FreeBSD 9.0-STABLE），它们可以被配置 使用 、 和 参数。 可以省略一个或两个参数，在这种情况下，系统默认设置 的相应 socket 选项将生效。 例如onSO_KEEPALIVEoffSO_KEEPALIVETCP_KEEPIDLETCP_KEEPINTVLTCP_KEEPCNTkeepidlekeepintvlkeepcnt

so_keepalive=30m::10

将空闲超时 （） 设置为 30 分钟， 将探测间隔 （） 保留为其系统默认值， 并将 Probes count （） 设置为 10 个探针。TCP_KEEPIDLETCP_KEEPINTVLTCP_KEEPCNT

例：

listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

根据请求 URI 设置配置。

匹配是针对规范化的 URI 执行的， 解码以 “” 形式编码的文本后， 解析对相对路径组件 “” 的引用 和 “”“，以及可能压缩的 2 个或更多 相邻的斜杠转换为单个斜杠。%XX...

位置可以由前缀字符串或正则表达式定义。 正则表达式使用前面的 “” 修饰符（用于不区分大小写的匹配），或者 “” 修饰符（用于区分大小写的匹配）。 要查找与给定请求匹配的位置，nginx 首先检查 使用前缀字符串 （prefix locations） 定义的位置。 其中，匹配时间最长的 Location 前缀被选中并记住。 然后，按照正则表达式的出现顺序检查正则表达式 在配置文件中。 正则表达式的搜索在第一个匹配项 并使用相应的配置。 如果未找到与正则表达式的匹配项，则 使用前面记住的前缀位置的配置。~*~

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

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

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

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

此外，使用 “” 修饰符可以定义 URI 和 location 的完全匹配。 如果找到完全匹配项，则搜索将终止。 例如，如果 “” 请求频繁发生， 定义 “” 将加快处理速度 中，因为搜索会在第一个 比较。 这样的位置显然不能包含嵌套位置。=/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， “” 请求将匹配配置 B， “” 请求将匹配 配置 C， “” 请求将匹配配置 D，并且 “” 请求将匹配配置 E。//index.html/documents/document.html/images/1.gif/documents/1.jpg

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

如果位置由以斜杠字符结尾的前缀字符串定义，则 并且请求由 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 使用 “” 字符。 但是，出于安全考虑，最好避免转弯 压缩关闭。off/

如果在服务器级别指定了该Directives，则 可以使用 default server 中的值。 有关详细信息，请参阅 “虚拟 server selection“部分。

msie_padding on;

启用或禁用向状态 大于 400 将响应大小增加到 512 字节。

msie_refresh off;

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

open_file_cache off;

配置可存储的缓存：

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

  错误缓存应由 open_file_cache_errors Directives单独启用。

该Directives具有以下参数：

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，文件需要 描述符在缓存中保持打开状态。numberinactive

open_file_cache_valid 60s;

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

output_buffers 2 32k;

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

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

port_in_redirect on;

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

重定向中主服务器名称的使用由 server_name_in_redirect Directives。

postpone_output 1460;

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

read_ahead 0;

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

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

在 FreeBSD 上，使用从 FreeBSD 9.0-CURRENT 开始支持的 system 调用。 FreeBSD 7 必须打补丁。fcntl(O_READAHEAD,size)

recursive_error_pages off;

启用或禁用使用 error_page Directives执行多个重定向。 此类重定向的数量是有限的。

request_pool_size 4k;

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

reset_timedout_connection off;

启用或禁用重置超时连接 以及使用非标准代码 444 （1.15.2） 关闭的连接。 重置的执行方式如下。 在关闭套接字之前，将在其上设置该选项，超时值为 0。 当套接字关闭时，TCP RST 被发送到客户端，所有内存 Occupied by this socket 被释放。 这有助于避免保持已关闭的套接字和填充的缓冲区 长时间处于FIN_WAIT1状态。SO_LINGER

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

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

resolver 127.0.0.1 [::1]:5353;

地址可以指定为域名或 IP 地址， 具有可选端口（1.3.1、1.2.2）。 如果未指定 port，则使用端口 53。 名称服务器以循环方式查询。

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

默认情况下，nginx 将在解析时查找 IPv4 和 IPv6 地址。 如果不需要查找 IPv4 或 IPv6 地址， （1.23.1） 或 可以指定该参数。ipv4=offipv6=off

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

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

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

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

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

可选参数 （1.17.1） 启用请求和响应的 DNS 服务器统计信息的收集 在指定的 . 该参数作为我们商业订阅的一部分提供。status_zonezone

resolver_timeout 30s;

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

resolver_timeout 5s;

root html;

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

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

该文件将作为响应 “” 请求。/data/w3/i/top.gif/i/top.gif

该值可以包含变量、 except 和 .path$document_root$realpath_root

只需将 URI 添加到值 的Directives。 如果必须修改 URI，则应使用 alias Directives。root

satisfy all;

如果 all （） 或至少一个 ngx_http_access_module、ngx_http_auth_basic_module、ngx_http_auth_request_module、 或 ngx_http_auth_jwt_module 模块允许访问。allany

例：

location / {
    satisfy any;

    allow 192.168.1.0/32;
    deny  all;

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

send_lowat 0;

如果Directives设置为非零值，nginx 将尝试最小化 使用 kqueue 方法的任一标志对客户端套接字执行的发送作数 或 socket 选项。 在这两种情况下，都使用 specified。NOTE_LOWATSO_SNDLOWATsize

在 Linux、Solaris 和 Windows 上忽略此Directives。

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

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

在 1.7.11 版本之前，可以使用 .aio sendfile;

sendfile_max_chunk 2m;

限制可以 在一次呼叫中转移。 如果没有限制，一个快速连接可能会完全占用工作进程。sendfile()

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

设置虚拟服务器的配置。 基于 IP（基于 IP 地址）之间没有明确的区分 和基于名称（基于 “Host” 请求标头字段） 虚拟服务器。 相反，listen Directives描述所有 地址和端口，并且 server_name Directives列出了所有服务器名称。 示例配置在 “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） 用于其他Directives：

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

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

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

正则表达式中的命名捕获创建变量 （0.8.25） 稍后可以在其他Directives中使用：

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

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

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

如果Directives的参数设置为 “” （0.9.4），则 计算机的主机名已插入。$hostname

也可以指定一个空的服务器名称 （0.7.11）：

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

它允许此服务器在没有 “Host” 的情况下处理请求 header 字段 — 而不是默认服务器 — 对于给定的 address：port 对。 这是默认设置。

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

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

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

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

server_name_in_redirect off;

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

重定向中端口的使用由 port_in_redirect Directives。

server_names_hash_bucket_size 32|64|128;

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

server_names_hash_max_size 512;

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

server_tokens on;

启用或禁用在错误页面和 “Server” 响应标头字段。

参数 （1.11.10） 启用发射 internal版本名称以及 nginx 版本。build

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

subrequest_output_buffer_size 4k|8k;

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

该Directives仅适用于 subrequests 将响应正文保存到内存中。 例如，此类子请求由 SSI 创建。

tcp_nodelay on;

启用或禁用该选项。 当连接转换为 keep-alive 状态。 此外，它还在 SSL 连接上启用， 对于无缓冲代理， 以及 WebSocket 代理。TCP_NODELAY

tcp_nopush off;

启用或禁用 FreeBSD 上的 socket 选项 或 Linux 上的 socket 选项。 仅当使用 sendfile 时，才会启用这些选项。 启用该选项将允许TCP_NOPUSHTCP_CORK

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

检查是否存在按指定顺序排列的文件，并使用 用于请求处理的第一个找到的文件;加工 在当前上下文中执行。 文件的路径由参数 根据 root 和 alias Directives。 可以通过指定 名称末尾的斜杠，例如 “”。 如果未找到任何文件，则会进行internal重定向到最后一个参数中指定的文件。 例如：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;
}

该Directives等效于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检查 PHP 文件是否存在 在将请求传递给 FastCGI 服务器之前。

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

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

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

types_hash_bucket_size 64;

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

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

types_hash_max_size 1024;

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

underscores_in_headers off;

启用或禁用在客户端请求标头字段中使用下划线。 当禁用下划线时，请求名称 contain 下划线是 标记为无效并受 ignore_invalid_headers Directives的约束。

如果在服务器级别指定了该Directives，则 可以使用 default server 中的值。 有关详细信息，请参阅 “虚拟 server selection“部分。

variables_hash_bucket_size 64;

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

variables_hash_max_size 1024;

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

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

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

$arg_name

请求行中的参数name

$args

请求行中的参数

$binary_remote_addr

client address 的二进制形式，值的长度始终为 4 字节 对于 IPv4 地址或 16 字节（对于 IPv6 地址）

$body_bytes_sent

发送到客户端的字节数，不计算响应标头; 此变量与 Apache 模块的 “” 参数兼容%Bmod_log_config

$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

$document_root

root 或 alias Directives的值 对于当前请求

$document_uri

与$uri

$host

按以下优先顺序： host name 的 NAME 请求行，或者 “Host” 请求标头字段中的 host name，或 与请求匹配的服务器名称

$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

“” 如果请求是通过管道传输的，则为 “” 否则（1.3.12、1.2.7）p.

$proxy_protocol_addr

来自 PROXY 协议标头的客户端地址 （1.5.12）

必须事先通过设置参数 在 listen Directives中。proxy_protocol

$proxy_protocol_port

来自 PROXY 协议标头的 client 端口 （1.11.0）

必须事先通过设置参数 在 listen Directives中。proxy_protocol

$proxy_protocol_server_addr

来自 PROXY 协议标头的服务器地址 （1.17.6）

必须事先通过设置参数 在 listen Directives中。proxy_protocol

$proxy_protocol_server_port

来自 PROXY 协议标头的服务器端口 （1.17.6）

必须事先通过设置参数 在 listen Directives中。proxy_protocol

$proxy_protocol_tlv_name

来自 PROXY 协议标头 （1.23.2） 的 TLV。 可以是 TLV 类型名称或其数值。 在后一种情况下，该值为十六进制 ，并且应该以 ：name0x

$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) - 客户端传递的 host name 值
• 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 Directives中。proxy_protocol

$query_string

与$args

$realpath_root

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

$remote_addr

客户端地址

$remote_port

客户端端口

$remote_user

随 Basic 身份验证提供的用户名

$request

完整的原始请求行

$request_body

请求正文

变量的值在 locations 中可用 由 proxy_pass、fastcgi_pass、 uwsgi_pass 处理、 以及 scgi_pass Directives（当请求正文被读取到 内存缓冲区。

$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 Directives禁用。

$request_completion

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

$request_filename

文件路径，基于 root 或 alias Directives以及请求 URI

$request_id

唯一请求标识符 由 16 个随机字节生成，十六进制 （1.11.0）

$request_length

请求长度（包括请求行、标头和请求正文） (1.3.12, 1.2.7)

$request_method

request 方法，通常 “” 或 “”GETPOST

$request_time

请求处理时间（以秒为单位），分辨率为毫秒 (1.3.9, 1.2.6); 从客户端读取第一个字节以来经过的时间

$request_uri

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

$scheme

请求方案 “” 或 “”httphttps

$sent_http_name

任意响应标头字段; 变量名称的最后一部分是转换的字段名称 改为小写，破折号替换为下划线

$sent_trailer_name

在响应末尾发送的任意字段 （1.13.2）; 变量名称的最后一部分是转换的字段名称 改为小写，破折号替换为下划线

$server_addr

接受请求的服务器的地址

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

$server_name

接受请求的服务器的名称

$server_port

接受请求的服务器的端口

$server_protocol

request 协议，通常 “”, “”, “HTTP/2.0”， 或 “HTTP/3.0”HTTP/1.0HTTP/1.1

$status

响应状态（1.3.2、1.2.2）

$tcpinfo_rtt, , ,$tcpinfo_rttvar$tcpinfo_snd_cwnd$tcpinfo_rcv_space

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

$time_iso8601

ISO 8601 标准格式的本地时间（1.3.12、1.2.7）

$time_local

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

$uri

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

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