# ngx\_http\_core\_module * [指令](#directives) * [absolute\_redirect](#absolute_redirect) * [aio](#aio) * [aio\_write](#aio_write) * [alias](#alias) * [chunked\_transfer\_encoding](#chunked_transfer_encoding) * [client\_body\_buffer\_size](#client_body_buffer_size) * [client\_body\_in\_file\_only](#client_body_in_file_only) * [client\_body\_in\_single\_buffer](#client_body_in_single_buffer) * [client\_body\_temp\_path](#client_body_temp_path) * [client\_body\_timeout](#client_body_timeout) * [client\_header\_buffer\_size](#client_header_buffer_size) * [client\_header\_timeout](#client_header_timeout) * [client\_max\_body\_size](#client_max_body_size) * [connection\_pool\_size](#connection_pool_size) * [default\_type](#default_type) * [directio](#directio) * [directio\_alignment](#directio_alignment) * [disable\_symlinks](#disable_symlinks) * [error\_page](#error_page) * [etag](#etag) * [http](#http) * [if\_modified\_since](#if_modified_since) * [ignore\_invalid\_headers](#ignore_invalid_headers) * [internal](#internal) * [keepalive\_disable](#keepalive_disable) * [keepalive\_requests](#keepalive_requests) * [keepalive\_timeout](#keepalive_timeout) * [large\_client\_header\_buffers](#large_client_header_buffers) * [limit\_except](#limit_except) * [limit\_rate](#limit_rate) * [limit\_rate\_after](#limit_rate_after) * [lingering\_close](#lingering_close) * [lingering\_time](#lingering_time) * [lingering\_timeout](#lingering_timeout) * [listen](#listen) * [location](#location) * [log\_not\_found](#log_not_found) * [log\_subrequest](#log_subrequest) * [max\_ranges](#max_ranges) * [merge\_slashes](#merge_slashes) * [msie\_padding](#msie_padding) * [msie\_refresh](#msie_refresh) * [open\_file\_cache](#open_file_cache) * [open\_file\_cache\_errors](#open_file_cache_errors) * [open\_file\_cache\_min\_uses](#open_file_cache_min_uses) * [open\_file\_cache\_valid](#open_file_cache_valid) * [output\_buffers](#output_buffers) * [port\_in\_redirect](#port_in_redirect) * [postpone\_output](#postpone_output) * [read\_ahead](#read_ahead) * [recursive\_error\_pages](#recursive_error_pages) * [request\_pool\_size](#request_pool_size) * [reset\_timedout\_connection](#reset_timedout_connection) * [resolver](#resolver) * [resolver\_timeout](#resolver_timeout) * [root](#root) * [satisfy](#satisfy) * [send\_lowat](#send_lowat) * [send\_timeout](#send_timeout) * [sendfile](#sendfile) * [sendfile\_max\_chunk](#sendfile_max_chunk) * [server](#server) * [server\_name](#server_name) * [server\_name\_in\_redirect](#server_name_in_redirect) * [server\_names\_hash\_bucket\_size](#server_names_hash_bucket_size) * [server\_names\_hash\_max\_size](#server_names_hash_max_size) * [server\_tokens](#server_tokens) * [tcp\_nodelay](#tcp_nodelay) * [tcp\_nopush](#tcp_nopush) * [try\_files](#try_files) * [types](#types) * [types\_hash\_bucket\_size](#types_hash_bucket_size) * [types\_hash\_max\_size](#types_hash_max_size) * [underscores\_in\_headers](#underscores_in_headers) * [variables\_hash\_bucket\_size](#variables_hash_bucket_size) * [variables\_hash\_max\_size](#variables_hash_max_size) * [内嵌变量](#embedded_variables) ## 指令 ### absolute\_redirect | - | 说明 | | ------- | ------------------------------------- | | **语法** | **absolute\_redirect** `on` \| `off`; | | **默认** | absolute\_redirect on; | | **上下文** | http、server、location | | **提示** | 该指令在 1.11.8 版本中出现 | 如果禁用，nginx 发出的重定向将是相对的。 另请参阅 [server\_name\_in\_redirect](#server_name_in_redirect) 和 [port\_in\_redirect](#port_in_redirect) 指令。 ### aio | - | 说明 | | ------- | ------------------------------------------ | | **语法** | **aio** `on` \| `off` \| `threads[=pool]`; | | **默认** | aio off; | | **上下文** | http、server、location | | **提示** | 该指令在 0.8.11 版本中出现 | 启用或禁用在 FreeBSD 和 Linux 上使用异步文件 I/O（AIO）： ```nginx location /video/ { aio on; output_buffers 1 64k; } ``` 在 FreeBSD 上，AIO 从 FreeBSD 4.3 开始可用。在 FreeBSD 11.0 之前，可以将 AIO 静态链接到内核中： ```nginx options VFS_AIO ``` 或作为一个内核可加载模块动态加载： ```nginx kldload aio ``` 在 Linux 上，AIO 从内核版本为 2.6.22 开始可用。此外，有必要启用 [directio](#directio)，否则读取将被阻塞： ```nginx location /video/ { aio on; directio 512; output_buffers 1 128k; } ``` 在 Linux 上，[directio](#directio) 只能用于读取 512 字节边界对齐的块（或 XFS 4K）。文件未对齐的末端以阻塞模式读取。对于字节范围请求和不是从文件开头开始的 FLV 请求也是如此：在文件的开头和结尾读取未对齐的数据将被阻塞。 当在 Linux 上启用 AIO 和 [sendfile](#sendfile) 时，AIO 用于大于或等于 [directio](#directio) 指令指定大小的文件，而 [sendfile](#sendfile) 用于较小的文件（禁用 [directio](#directio) 时也是如此）。 ```nginx location /video/ { sendfile on; aio on; directio 8m; } ``` 最后，可以使用多线程（1.7.11）读取和[发送](#sendfile)文件，不会阻塞工作进程： ```nginx location /video/ { sendfile on; aio threads; } ``` 读取和发送文件操作被卸载到指定[池](#thread_pool)中的线程。如果省略池名称，则使用名称为 `default` 的池。池名也可以用变量设置： ```nginx aio threads=pool$disk; ``` 默认情况下，多线程是禁用状态，它应该使用 `--with-threads` 配置参数启用。目前，多线程仅与 [epoll](http://nginx.org/en/docs/events.html#epoll)、[kqueue](http://nginx.org/en/docs/events.html#kqueue) 和 [eventport](http://nginx.org/en/docs/events.html#eventport) 方式兼容。仅在 Linux 上支持多线程发送文件。 另请参见 [sendfile](#sendfile) 指令。 ### aio\_write | - | 说明 | | ------- | ----------------------------- | | **语法** | **aio\_write** `on` \| `off`; | | **默认** | aio\_write off; | | **上下文** | http、server、location | | **提示** | 该指令在 1.9.13 版本中出现 | 如果启用 [aio](#aio)，则指定是否写入文件。目前，这仅在使用 aio 线程时有效，并且仅限于将从代理服务器接收的数据写入临时文件。 ### alias | - | 说明 | | ------- | ----------------- | | **语法** | **alias** `path`; | | **默认** | —— | | **上下文** | location | 定义指定 location 的替换。例如，使用以下配置 ```nginx location /i/ { alias /data/w3/images/; } ``` `/i/top.gif` 的请求，将发送 `/data/w3/images/top.gif` 文件。 `path` 值可以包含变量，除 `$document_root` 和 `$realpath_root` 外。 如果在使用正则表达式定义的 location 内使用了别名，那么这种正则表达式应该包含捕获，并且别名应该引用这些捕获（0.7.40），例如： ```nginx location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { alias /data/w3/images/$1; } ``` 当 location 与指令值的最后一部分匹配时： ```nginx location /images/ { alias /data/w3/images/; } ``` 更好的方式是使用 [root](#root) 指令： ```nginx location /images/ { root /data/w3; } ``` ### chunked\_transfer\_encoding | - | 说明 | | ------- | ---------------------------------------------- | | **语法** | **chunked\_transfer\_encoding** `on` \| `off`; | | **默认** | chunked\_transfer\_encoding on; | | **上下文** | http、server、location | 允许在 HTTP/1.1 中禁用分块传输编码。在使用的软件未能支持分块编码时它可能会派上用场。 ### client\_body\_buffer\_size | - | 说明 | | ------- | -------------------------------------- | | **语法** | **client\_body\_buffer\_size** `size`; | | **默认** | client\_body\_buffer\_size 8k | | **上下文** | http、server、location | 设置读取客户端请求体的缓冲区大小。如果请求体大于缓冲区，则整个体或仅将其部分写入[临时文件](#client_body_temp_path)。默认情况下，缓冲区大小等于两个内存页。在 x86、其他 32 位平台和 x86-64 上是 8K。在其他 64 位平台上通常为 16K。 ### client\_body\_in\_file\_only | - | 说明 | | ------- | ---------------------------------------------------------- | | **语法** | **client\_body\_in\_file\_only** `on` \| `clean` \| `off`; | | **默认** | client\_body\_in\_file\_only off; | | **上下文** | http、server、location | 确定 nginx 是否应将整个客户端请求体保存到文件中。可以在调试期间或使用 `$request_body_file` 变量或模块 [ngx\_http\_perl\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_perl_module) 的 [$r->request\_body\_file](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_perl_module#methods) 方法时使用此指令。 当设置为 `on` 值时，临时文件在请求处理后不会被删除。 值 `clean` 会将请求处理后剩下的临时文件删除。 ### client\_body\_in\_single\_buffer | - | 说明 | | ------- | --------------------------------------------------- | | **语法** | **client\_body\_in\_single\_buffer** `on` \| `off`; | | **默认** | client\_body\_in\_single\_buffer off; | | **上下文** | http、server、location | 确定 nginx 是否应将整个客户端请求体保存在单个缓冲区中。在使用 `$request_body` 变量时，建议使用该指令，用来保存涉及的复制操作次数。 ### client\_body\_temp\_path | - | 说明 | | ------- | --------------------------------------------------------------- | | **语法** | **client\_body\_temp\_path** `path [level1 [level2 [level3]]]`; | | **默认** | client\_body\_temp\_path client\_body\_temp; | | **上下文** | http、server、location | 定义用于存储持有客户端请求主体的临时文件的目录。最多可以在指定目录下使用三级子目录层次结构。例如以下配置 ```nginx client_body_temp_path /spool/nginx/client_temp 1 2; ``` 临时文件的路径可以如下： ```nginx /spool/nginx/client_temp/7/45/00000123457 ``` ### client\_body\_timeout | - | 说明 | | ------- | --------------------------------- | | **语法** | **client\_body\_timeout** `time`; | | **默认** | client\_body\_timeout 60s; | | **上下文** | http、server、location | 定义读取客户端请求正文的超时时间。超时设置仅是在两个连续读操作之间的时间间隔，而不是整个请求体的传输过程。如果客户端在此时间内没有发送任何内容，则会将 408（请求超时）错误返回给客户端。 ### client\_header\_buffer\_size | - | 说明 | | ------- | ---------------------------------------- | | **语法** | **client\_header\_buffer\_size** `size`; | | **默认** | client\_header\_buffer\_size 1k; | | **上下文** | http、server | 设置读取客户端请求头的缓冲区大小。对于大多数请求，1K 字节的缓冲区就足够了。但是，如果请求中包含长 cookie，或者来自 WAP 客户端，则可能 1K 是不适用的。如果请求行或请求头域不适合此缓冲区，则会分配由 [large\_client\_header\_buffers](#large_client_header_buffers) 指令配置的较大缓冲区。 ### client\_header\_timeout | - | 说明 | | ------- | ----------------------------------- | | **语法** | **client\_header\_timeout** `time`; | | **默认** | client\_header\_timeout 60s; | | **上下文** | http、server | 定义读取客户端请求头的超时时间。如果客户端在这段时间内没有传输整个报头，则将 408（请求超时）错误返回给客户端。 ### client\_max\_body\_size | - | 说明 | | ------- | ----------------------------------- | | **语法** | **client\_header\_timeout** `size`; | | **默认** | client\_max\_body\_size 1m; | | **上下文** | http、server、location | 在 **Content-Length** 请求头域中指定客户端请求体的最大允许大小。如果请求的大小超过配置值，则将 413 （请求实体过大）错误返回给客户端。请注意，浏览器无法正确显示此错误。将 `size` 设置为 0 将禁用检查客户端请求正文大小。 ### connection\_pool\_size | - | 说明 | | ------- | ---------------------------------- | | **语法** | **connection\_pool\_size** `size`; | | **默认** | connection\_pool\_size 256 | | **上下文** | http、server | 允许精确调整每个连接的内存分配。该指令对性能影响最小，一般不建议使用。默认情况下，32 位平台上的大小为 256 字节，64 位平台上为 512 字节。 > 在 1.9.8 版本之前，所有平台上的默认值都为 256。 ### default\_type | - | 说明 | | ------- | ------------------------------ | | **语法** | **default\_type** `mime-type`; | | **默认** | default\_type text/plain; | | **上下文** | http、server、location | 定义响应的默认 MIME 类型。可以使用 [types](#types) 指令对 MIME 类型的文件扩展名进行映射。 ### directio | - | 说明 | | ------- | ----------------------------- | | **语法** | **directio** `size` \| `off`; | | **默认** | directio off; | | **上下文** | http、server、location | 开启当读取大于或等于指定大小的文件时，使用 `O_DIRECT` 标志（FreeBSD、Linux）、`F_NOCACHE` 标志（macOS）或 `directio()` 函数（Solaris）。该指令自动禁用（0.7.15）给定请求使用的 [sendfile](#sendfile)。它可以用于服务大文件： ```nginx directio 4m; ``` 或当在 Linux 上使用 [aio](#aio) 时。 ### directio\_alignment | - | 说明 | | ------- | ------------------------------- | | **语法** | **directio\_alignment** `size`; | | **默认** | directio\_alignment 512; | | **上下文** | http、server、location | | **提示** | 该指令在 0.8.11 版本中出现 | 设置 [directio](#directio) 的对齐方式。在大多数情况下，512 字节的对齐就足够了。但是，在 Linux 下使用 XFS 时，需要增加到 4K。 ### disable\_symlinks | - | 说明 | | | ------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------- | | **语法** |

disable\_symlinks off;
disable\_symlinks on | if\_not\_owner \[from=part];

| | **默认** | disable\_symlinks off; | | | **上下文** | http、server、location | | | **提示** | 该指令在 1.1.15 版本中出现 | | 确定打开文件时应如何处理符号链接： * `off` 允许路径名中的符号链接的，不执行检查。这是默认行为。 * `on` 如果路径名存在是符号链接的组件，则拒绝对文件的访问。 * `if_not_owner` 如果路径名存在是符号链接的组件，并且链接指向的链接和对象为不同所有者，则拒绝访问文件。 * `from=part` 当检查符号链接（参数 `on` 和 `if_not_owner`）时，通常会检查路径名的所有组件。可以通过另外指定 `from=part` 参数来避免检查路径名的初始部分中的符号链接。在这种情况下，只能从指定的初始部分后面的路径名组件检查符号链接。如果该值不是检查的路径名的初始部分，则会检查整个路径名，相当于没有指定此参数。如果该值与整个文件名匹配，则不会检查符号链接。参数值可以包含变量。 例如： ```nginx disable_symlinks on from=$document_root; ``` 此指令仅适用于具有 `openat()` 和 `fstatat()` 接口的系统。这样的系统包括现代版本的FreeBSD、Linux 和 Solaris。 参数 `on` 和 `if_not_owner` 增加了处理开销。 > 在不支持打开目录仅用于搜索的系统上，要使用这些参数，需要 worker 进程对所有正在检查的目录具有读取权限。 > [ngx\_http\_autoindex\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_autoindex_module)、[ngx\_http\_random\_index\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_random_index_module) 和 [ngx\_http\_dav\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_dav_module) 模块目前忽略此指令。 ### error\_page | - | 说明 | | ------- | --------------------------------------------- | | **语法** | **error\_page** `code ... [=[response]] uri`; | | **默认** | —— | | **上下文** | http、server、location、location 中的 if | 定义针对指定错误显示的 URI。`uri` 值可以包含变量。 例如： ```nginx error_page 404 /404.html; error_page 500 502 503 504 /50x.html; ``` 这会导致客户端请求方法更改为 `GET`，内部重定向到指定的 `uri`（除 `GET` 和 `HEAD` 之外的所有方法）。 此外，可以使用 `=response` 语法将修改响应代码，例如： ```nginx error_page 404 =200 /empty.gif; ``` 如果错误响应是由代理服务器或 FastCGI/uwsgi/SCGI 服务器处理，并且服务器可能返回不同的响应代码（例如，200、302、401 或 404），则可以使用其返回的代码进行响应： ```nginx error_page 404 = /404.php; ``` 如果在内部重定向时不需要更改 URI 和方法，则可以将错误处理传递给一个命名了的 location： ```nginx location / { error_page 404 = @fallback; } location @fallback { proxy_pass http://backend; } ``` > 如果 `uri` 处理导致发生错误，最后发生错误的状态代码将返回给客户端。 也可以使用 URL 重定向进行错误处理： ```nginx 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 | - | 说明 | | ------- | ----------------------- | | **语法** | **etag** `on` \| `off`; | | **默认** | etag on; | | **上下文** | http、server、location | | **提示** | 该指令在 1.3.3 版本中出现 | 启用或禁用自动生成静态资源 **ETag** 响应头字段。 ### http | - | 说明 | | ------- | ------------------- | | **语法** | **http** `{ ... }`; | | **默认** | —— | | **上下文** | main | 提供指定 HTTP server 指令的配置文件上下文。 ### if\_modified\_since | - | 说明 | | ------- | ----------------------------------------------------- | | **语法** | **if\_modified\_since** `off` \| `exact` \| `before`; | | **默认** | if\_modified\_since exact; | | **上下文** | http、server、location | | **提示** | 该指令在 0.7.24 版本中出现 | 指定如何将响应的修改时间与 **If-Modified-Since** 请求头字段中的时间进行比较： * `off` 忽略 **If-Modified-Since** 请求头字段（0.7.34） * `exact` 完全匹配 * `before` 响应的修改时间小于或等于 **If-Modified-Since** 请求头字段中的时间 ### ignore\_invalid\_headers | - | 说明 | | ------- | ------------------------------------------- | | **语法** | **ignore\_invalid\_headers** `on` \| `off`; | | **默认** | ignore\_invalid\_headers on; | | **上下文** | http、server | 控制是否应忽略具有无效名称的头字段。有效名称由英文字母、数字、连字符或下划线组成（由 [underscores\_in\_headers](#underscores_in_headers) 指令控制）。 如果在 [server](#server) 级别指定了该指令，则其值仅在 server 为默认 server 时使用。指定的值也适用于监听相同地址和端口的所有虚拟服务器。 ### internal | - | 说明 | | ------- | ------------- | | **语法** | **internal**; | | **默认** | —— | | **上下文** | location | 指定给定的 location 只能用于内部请求。对于外部请求，返回客户端错误 404（未找到）。内部请求如下： * 请求由 [error\_page](#error_page)、[index](#index)、[random\_index](#random_index) 和 [try\_files](#try_files) 指令重定向 * 来 upstream server 的 **X-Accel-Redirect** 响应头字段重定向的请求 * 由 [ngx\_http\_ssi\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_ssi_module) 模块的 `include virtual` 命令、[ngx\_http\_addition\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_addition_module) 模块指令和 [auth\_request](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_auth_request_module#auth_request) 和 [mirror](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_mirror_module#mirror) 指令组成的子请求 * 由 [rewrite](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_rewrite_module#rewrite) 指令更改的请求 示例： ```nginx error_page 404 /404.html; location /404.html { internal; } ``` > 每个请求限制 10 个内部重定向，以防止不正确配置引发的请求处理死循环。如果达到此限制，则返回错误 500（内部服务器错误）。在这种情况下，可以在错误日志中看到 `rewrite or internal redirection cycle` 消息。 ### keepalive\_disable | - | 说明 | | ------- | ----------------------------------------------- | | **语法** | **keepalive\_disable** `none` \| `browser ...`; | | **默认** | keepalive\_disable msie6; | | **上下文** | http、server、location | 禁用与行为异常的浏览器保持连接。`browser` 参数指定哪些浏览器将受到影响。一旦接收到 POST 请求，值 `msie6` 将禁用与旧版本 MSIE 保持连接。值 `safari` 禁用与 macOS 和类似 MacOS 的操作系统上的 Safari 和 Safari 浏览器保持连接。值 `none` 启用与所有浏览器保持连接。 > 在 1.1.18 版本之前，值 `safari` 匹配所有操作系统上的所有 Safari 和类 Safari 浏览器，并且默认情况下，禁用与它们保持连接。 ### keepalive\_requests | - | 说明 | | ------- | --------------------------------- | | **语法** | **keepalive\_requests** `number`; | | **默认** | keepalive\_requests 100; | | **上下文** | http、server、location | | **提示** | 该指令在 0.8.0 版本中出现 | 设置通过一个保持活动（keep-alive）连接可以提供的最大请求数。在发出的请求达到最大数量后，连接将被关闭。 ### keepalive\_timeout | - | 说明 | | ------- | ---------------------------------------------------- | | **语法** | **keepalive\_timeout** `timeout` `[header_timeout]`; | | **默认** | keepalive\_timeout 75s; | | **上下文** | http、server、location | 第一个参数设置一个超时时间，keep-alive 客户端连接将在服务端保持打开状态。零值将禁用 keep-alive 客户端连接。可选的第二个参数在 **Keep-Alive: timeout=`time`** 响应头域中设置一个值。两个参数可能不同。 Mozilla 和 Konqueror 会识别 \*\*Keep-Alive: timeout=`time` 头字段。MSIE 在大约在 60 秒钟内自行关闭 keep-alive 连接。 ### large\_client\_header\_buffers | - | 说明 | | ------- | ------------------------------------------------- | | **语法** | **large\_client\_header\_buffers** `number size`; | | **默认** | arge\_client\_header\_buffers 4 8k; | | **上下文** | http、server | 设置用于读取大客户端请求头的缓冲区的最大 `number`（数量）和 `size`（大小）。请求行不能超过一个缓冲区的大小，否则将返回 414（请求 URI 太长）错误给客户端。请求头字段也不能超过一个缓冲区的大小，否则将返回 400（错误请求）错误给客户端。缓冲区只能按需分配。默认情况下，缓冲区大小等于 8K 字节。如果在请求处理结束之后，连接被转换为 keep-alive 状态，这些缓冲区将被释放。 ### limit\_except | - | 说明 | | ------- | --------------------------------------- | | **语法** | **limit\_except** `method ... { ... }`; | | **默认** | —— | | **上下文** | location | 限制给定的 location 内允许的 HTTP 方法。`method` 参数可以是以下之一：`GET`、`HEAD`、`POST`、`PUT`、`DELETE`、`MKCOL`、`COPY`、`MOVE`、`OPTIONS`、`PROPFIND`、`PROPPATCH`、`LOCK`、`UNLOCK` 或 `PATCH`。允许 `GET` 方法也将使得 `HEAD`方法被允许。可以使用 [ngx\_http\_access\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_access_module) 和 [ngx\_http\_auth\_basic\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_auth_basic_module) 模块指令来限制对其他方法的访问： ```nginx limit_except GET { allow 192.168.1.0/32; deny all; } ``` 请注意，这将限制访问除 `GET` 和 `HEAD` 之外的所有方法。 ### limit\_rate | - | 说明 | | ------- | ----------------------------------- | | **语法** | **limit\_rate** `rate`; | | **默认** | limit\_rate 0; | | **上下文** | http、server、location、location 中的 if | 限制客户端的响应传输速率。`rate` 以字节/秒为单位。零值将禁用速率限制。限制设置是针对每个请求，因此如果客户端同时打开两个连接，则整体速率将是指定限制的两倍。 也可以在 `$limit_rate` 变量中设置速率限制。根据某些条件来限制速率可能会有用： ```nginx server { if ($slow) { set $limit_rate 4k; } ... } ``` 也可以在代理服务器响应的 **X-Accel-Limit-Rate** 头字段中设置速率限制。可以使用 [proxy\_ignore\_headers](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_proxy_module#proxy_ignore_headers)、[fastcgi\_ignore\_headers](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_fastcgi_module#fastcgi_ignore_headers)、[uwsgi\_ignore\_headers](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_uwsgi_module#uwsgi_ignore_headers) 和 [scgi\_ignore\_headers](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_scgi_module#scgi_ignore_headers) 指令禁用此功能。 ### lingering\_time | - | 说明 | | ------- | --------------------------- | | **语法** | **lingering\_time** `time`; | | **默认** | lingering\_time 30s; | | **上下文** | http、server、location | 当 [lingering\_close](#lingering_close) 生效时，该指令指定 nginx 处理（读取和忽略）来自客户端的额外数据的最长时间。之后，连接将被关闭，即使还有更多的数据。 ### lingering\_timeout | - | 说明 | | ------- | ------------------------------ | | **语法** | **lingering\_timeout** `time`; | | **默认** | lingering\_timeout 5s; | | **上下文** | http、server、location | 当 [lingering\_close](#lingering_close) 生效时，该指令指定更多的客户端数据到达的最长等待时间。如果在此期间未收到数据，则关闭连接。否则，读取和忽略数据，nginx 再次开始等待更多的数据。**wait-read-ignore** 循环被重复，但不再由 [lingering\_time](#lingering_time) 指令指定。 ### listen | - | 说明 | | | | | | | | | | | | | ------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | --- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | --- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --- | ------------------------------------------------ | | **语法** |

listen address\[:port] \[default\_server] \[ssl] \[http2 | spdy] \[proxy\_protocol] \[setfib=number] \[fastopen=number] \[backlog=number] \[rcvbuf=size] \[sndbuf=size] \[accept\_filter=filter] \[deferred] \[bind] \[ipv6only=on | off] \[reuseport] \[so\_keepalive=on | off | \[keepidle]:\[keepintvl]:\[keepcnt]];
listen port \[default\_server] \[ssl] \[http2 | spdy] \[proxy\_protocol] \[setfib=number] \[fastopen=number] \[backlog=number] \[rcvbuf=size] \[sndbuf=size] \[accept\_filter=filter] \[deferred] \[bind] \[ipv6only=on | off] \[reuseport] \[so\_keepalive=on | off | \[keepidle]:\[keepintvl]:\[keepcnt]];
listen unix:path \[default\_server] \[ssl] \[http2 | spdy] \[proxy\_protocol] \[backlog=number] \[rcvbuf=size] \[sndbuf=size] \[accept\_filter=filter] \[deferred] \[bind] \[so\_keepalive=on | off | \[keepidle]:\[keepintvl]:\[keepcnt]];

| | **默认** | listen \*:80 \| \*:8000; | | | | | | | | | | | | | **上下文** | server | | | | | | | | | | | | 设置 IP 的 `address` （地址）和 `port` （端口），或服务器接受请求的 UNIX 域套接字的 `path` （路径）。可以同时指定 `addres` （地址）和 `port` （端口），也可以只指定 `address` （地址）或 `port` （端口）。`address` 也可以是主机名，例如： ```nginx listen 127.0.0.1:8000; listen 127.0.0.1; listen 8000; listen *:8000; listen localhost:8000; ``` IPv6 地址（0.7.36）在方括号中指定： ```nginx listen [::]:8000; listen [::1]; ``` UNIX 域套接字（0.8.21）用 `unix:` 前缀指定： ```nginx 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 请求的服务器提供更紧凑的[配置](https://github.com/DocsHome/nginx-docs/blob/master/%E6%A8%A1%E5%9D%97%E5%8F%82%E8%80%83/http/%E4%BB%8B%E7%BB%8D/%E9%85%8D%E7%BD%AEHTTPS%E6%9C%8D%E5%8A%A1%E5%99%A8.md#single_http_https_server)。 `http2` 参数（1.9.5）配置端口接受 [HTTP/2](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_v2_module) 连接。通常，为了能够工作，还应该指定 `ssl` 参数，但也可以将 nginx 配置为接受没有 SSL 的 HTTP/2 连接。 `spdy` 参数（1.3.15 — 1.9.4）允许在此端口上接受 [SPDY](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_spdy_module) 连接。通常，为了能够工作，还应该指定 `ssl` 参数，但也可以将 nginx 配置为接受没有 SSL 的 SPDY 连接。 `proxy_protocol` 参数（1.5.12）允许指定此端口上接受的所有连接都应使用 [PROXY 协议](http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt)。 `listen` 指令可以有特定于套接字相关系统调用的几个附加参数。这些参数可以在任何 `listen` 指令中指定，但对于给定的 `address:port` 只能使用一次。 > 在 0.8.21 之前的版本中，它们只能在 `listen` 指令中与默认参数一起指定。 * `setfib=number` 此参数（0.8.44）设置相关联的路由表，监听套接字的 FIB（`SO_SETFIB` 选项）。目前只适用于 FreeBSD。 * `fastopen=number` 为侦听套接字启用 [**TCP Fast Open**](http://en.wikipedia.org/wiki/TCP_Fast_Open) （1.5.8），并限制尚未完成三次握手的连接队列的最大长度。 > 不要启用此功能，除非服务器可以一次处理接收多个[相同的 SYN 包的数据](https://tools.ietf.org/html/rfc7413#section-6.1)。 * `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](http://man.freebsd.org/accf_data) 或 [httpready](http://man.freebsd.org/accf_http)。 * `deferred` 指示在 Linux 上使用延迟 `accept()`（`TCP_DEFER_ACCEPT` 套接字选项）。 * `bind` 指示为给定的 `address:port` 对单独进行 `bind()` 调用。这是有用的，因为如果有多个有相同端口但不同地址的 `listen` 指令，并且其中一个 `listen` 指令监听给定端口（`*:port`）的所有地址，则 nginx 将 `bind()` 应用到`*:port`。应该注意的是，在这种情况下将会进行 `getsockname()` 系统调用，以确定接受该连接的地址。如果使用 `setfib`、`backlog`、`rcvbuf`、`sndbuf`、`accept_filter`、`deferred`、`ipv6only` 或 `so_keepalive` 参数，那么对于给定的 `address:port` 对将始终进行单独的 `bind()` 调用。 * `ipv6only=ON|OFF` 此参数（0.7.42）确定（通过 `IPV6_V6ONLY` 套接字选项）一个监听通配符地址 `[::]` 的 IPv6 套接字是否仅接受 IPv6 连接或 IPv6 和 IPv4 连接。此参数默认为开启。它只能在启动时设置一次。 > 在 1.3.4 版本之前，如果省略该参数，则操作系统的设置将对于套接字产生影响。 * `reuseport` 此参数（1.9.1）指示为每个工作进程创建一个单独的监听套接字（使用 `SO_REUSEPORT` 套接字选项），允许内核在工作进程之间分配传入的连接。目前只适用于 Linux 3.9+ 和 DragonFly BSD。 > 不当地使用此选项可能会带来安全[隐患](http://man7.org/linux/man-pages/man7/socket.7.html)。 * `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` 参数进行配置。可以省略一个或两个参数，在这种情况下，相应套接字选项的系统默认设置将生效。例如， ```nginx SO_KEEPALIVE=30m::10 ``` 将空闲超时（`TCP_KEEPIDLE`）设置为 30 分钟，将探测间隔（`TCP_KEEPINTVL`）设置为系统默认值，并将探测数量（`TCP_KEEPCNT`）设置为 10 个探测。 示例： ```nginx listen 127.0.0.1 default_server accept_filter=dataready backlog=1024; ``` ### location | - | 说明 | | | | | ------- | --------------------------------------- | -- | ---- | -------------------------------------------------------------------------------------- | | **语法** |

location \[ = | \~ | \~\* | ^\~ ] uri { ... };
location @name { ... };

| | **默认** | —— | | | | | **上下文** | server、location | | | | 根据请求 URI 设置配置。 在解码以 `％XX` 形式编码的文本，解析对相对路径组件 `.` 和`..` 的引用并且将两个或更多个相邻斜线[压缩](#merge_slashes)成单斜线之后，对规范化的 URI 执行匹配。 location 可以由前缀字符串定义，也可以由正则表达式定义。正则表达式前面使用`~*`修正符（用于不区分大小写的匹配）或 `~` 修正符（用于区分大小写的匹配）指定。要查找匹配给定请求的 location，nginx 首先检查使用前缀字符串（前缀 location）定义的 location。期间，前缀最长的 location 被匹配选中并记住。然后按照它们在配置文件中出现的顺序检查正则表达式。正则表达式的搜索将在第一次匹配时终止，并使用相应的配置。如果找不到正则表达式的匹配，则使用先前记住的前缀 location 的配置。 location 块可以嵌套，除了下面提到的一些例外。 对于不区分大小写的操作系统，如 macOS 和 Cygwin，与前缀字符串匹配忽略大小写（0.7.7）。但是，比较仅限于一个字节的区域设置。 正则表达式可以包含捕获（0.7.40），之后可以在其他指令中使用。 如果最长匹配的前缀 location 具有 `^~` 修正符，则不检查正则表达式。 另外，使用 `=` 修正符可以使 URI 和 location 的匹配精确。如果找到完全匹配，则搜索结束。例如，如果 `/` 请求频繁，那么定义 `location=/` 会加快这些请求的处理速度，因为搜索在第一次比较之后会立即终止。这样的 location 不能包含嵌套 location。 > 从 0.7.1 到 0.8.41 版本，如果请求与没有 `=` 和 `^~` 修正符的前缀 location 匹配，则搜索也会终止，并且不再检查正则表达式。 下面举一个例子来说明： ```nginx 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](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_proxy_module#proxy_pass)、[fastcgi\_pass](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_fastcgi_module#fastcgi_pass)、[uwsgi\_pass](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_uwsgi_module#uwsgi_pass)、[scgi\_pass](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_scgi_module#scgi_pass) 或 [memcached\_pa​​ss](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_memcached_module#memcached_pass) 中的一个进行处理，则会执行特殊处理。为了响应 URI 为该字符串的请求，但没有以斜杠结尾，带有 301 代码的永久重定向将返回所请求的 URI，并附上斜线。如果不需要，可以像以下这样定义 URI 和 location 的精确匹配： ```nginx location /user/ { proxy_pass http://user.example.com; } location = /user { proxy_pass http://login.example.com; } ``` ### log\_not\_found | - | 说明 | | ------- | -------------------------------- | | **语法** | **log\_not\_found** `on \| off`; | | **默认** | log\_not\_found on; | | **上下文** | http、server、location | 启用或禁用将文件未找到错误记录到 [error\_log](#error_log) 中。 ### log\_subrequest | - | 说明 | | ------- | -------------------------------- | | **语法** | **log\_subrequest** `on \| off`; | | **默认** | log\_subrequest off; | | **上下文** | http、server、location | 启用或禁用将子请求记录到 [access\_log](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_log_module#access_log) 中。 ### max\_ranges | - | 说明 | | ------- | ---------------------------- | | **语法** | **merge\_slashes** `number`; | | **默认** | —— | | **上下文** | http、server、location | | **提示** | 该指令在 1.1.2 版本中出现 | 限制 byte-range 请求中允许的最大范围数。如果没有指定字节范围，则处理超出限制的请求。 默认情况下，范围的数量不受限制。零值将完全禁用 byte-range 支持。 ### merge\_slashes | - | 说明 | | ------- | ------------------------------- | | **语法** | **merge\_slashes** `on \| off`; | | **默认** | merge\_slashes on; | | **上下文** | http、server | 启用或禁用将 URI 中两个或多个相邻斜线压缩为单斜线。 请注意，压缩对于正确匹配前缀字符串和正则表达式的 location 非常重要。没有它，将不匹配 `//scripts/one.php` 请求： ```nginx location /scripts/ { ... } ``` 并可能被作为一个静态文件处理。因此它需要被转换成 `/scripts/one.php`。 因为 base64 在内部使用 `/` 字符，所以如果 URI 包含 base64 编码的名称，则可能需要关闭压缩。但是，出于安全考虑，最好不要关闭压缩。 如果该指令是在 [server](#server) 级别指定的，则仅在 server 是默认 server 时才使用该指令。指定的值也适用于监听相同地址和端口的所有虚拟服务器。 ### msie\_padding | - | 说明 | | ------- | ------------------------------ | | **语法** | **msie\_padding** `on \| off`; | | **默认** | msie\_padding on; | | **上下文** | http、server、location | 启用或禁用向状态超过 400 的 MSIE 客户端响应添加注释以将响应大小增加到 512 字节。 ### msie\_refresh | - | 说明 | | ------- | ------------------------------ | | **语法** | **msie\_refresh** `on \| off`; | | **默认** | msie\_refresh off; | | **上下文** | http、server、location | 启用或禁用发布刷新替代 MSIE 客户端重定向。 ### open\_file\_cache | - | 说明 | | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **语法** |

open\_file\_cache off;
open\_file\_cache max=N \[inactive=time];

| | **默认** | open\_file\_cache off; | | **上下文** | http、server、location | 配置一个缓存，可以存储： * 打开文件描述符、大小和修改时间 * 有关目录是否存在信息 * 文件查找错误，如**找不到文件**、**没有读取权限**等 > 应该通过 [open\_file\_cache\_errors](#open_file_cache_errors) 指令分别启用缓存错误。 该指令有以下参数： * `max` 设置缓存中元素的最大数量。在缓存溢出时，最近最少使用的（LRU）元素将被移除 * `inactive` 定义一个时间，在这个时间之后，元素在缓存中将被删除，默认是 60 秒 * `off` 禁用缓存 示例： ```nginx 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 | - | 说明 | | ------- | -------------------------------------------- | | **语法** | **open\_file\_cache\_errors** `off` \| `on`; | | **默认** | open\_file\_cache\_errors off; | | **上下文** | http、server、location | 通过 [open\_file\_cache](#open_file_cache) 启用或禁用文件查找错误缓存。 ### open\_file\_cache\_min\_uses | - | 说明 | | ------- | ------------------------------------------ | | **语法** | **open\_file\_cache\_min\_uses** `number`; | | **默认** | open\_file\_cache\_min\_uses 1; | | **上下文** | http、server、location | 设置由 [open\_file\_cache](#open_file_cache) 指令的 `inactive` 参数配置的时间段内文件访问的最小 `number` （次数），这是文件描述符在缓存中保持打开状态所必需的。 ### open\_file\_cache\_valid | - | 说明 | | ------- | ------------------------------------ | | **语法** | **open\_file\_cache\_valid** `time`; | | **默认** | open\_file\_cache\_valid 60s; | | **上下文** | http、server、location | 设置 [open\_file\_cache](#open_file_cache) 元素应该验证的时间。 ### output\_buffers | - | 说明 | | ------- | ---------------------------------- | | **语法** | **output\_buffers** `number size`; | | **默认** | output\_buffers 2 32k; | | **上下文** | http、server、location | 设置从磁盘读取响应缓冲区的 `number` （数量）和 `size` （大小）。 > 在 1.9.5 版本之前，默认值是 `1 32k`。 ### port\_in\_redirect | - | 说明 | | ------- | ------------------------------------- | | **语法** | **port\_in\_redirect** `on` \| `off`; | | **默认** | port\_in\_redirect on; | | **上下文** | http、server、location | 启用或禁用指定由 nginx 发出的[绝对](#absolute_redirect)重定向中的端口。 > 在重定向中使用的主服务器名称由 [server\_name\_in\_redirect](#server_name_in_redirect) 指令控制。 ### postpone\_output | - | 说明 | | ------- | ---------------------------- | | **语法** | **postpone\_output** `size`; | | **默认** | postpone\_output 1460; | | **上下文** | http、server、location | 如果指定的话，客户端数据的传输将被推迟，直到 nginx 至少有 `size` 字节的数据要发送。零值将禁止延迟数据传输。 ### read\_ahead | - | 说明 | | ------- | ------------------------ | | **语法** | **read\_ahead** `sizef`; | | **默认** | read\_ahead 0; | | **上下文** | http、server、location | 设置使用文件时内核的预读数量。 在 Linux 上，使用 `posix_fadvise`（`0, 0, 0, POSIX_FADV_SEQUENTIAL`）系统调用，因此 `size` 参数将被忽略。 在 FreeBSD 上，使用自 FreeBSD 9.0-CURRENT 后支持的 `fcntl`（`O_READAHEAD, size`）系统调用。FreeBSD 7 需要[打补丁](http://sysoev.ru/freebsd/patch.readahead.txt)。 ### recursive\_error\_pages | - | 说明 | | ------- | ------------------------------------------ | | **语法** | **recursive\_error\_pages** `on` \| `off`; | | **默认** | reset\_timedout\_connection off; | | **上下文** | http、server、location | 启用或禁用使用 [error\_page](#error_page) 指令执行多个重定向。这种重定向的数量是[有限](#internal)的。 ### request\_pool\_size | - | 说明 | | ------- | ------------------------------- | | **语法** | **request\_pool\_size** `size`; | | **默认** | request\_pool\_size 4k; | | **上下文** | http、server | 允许精确调整每个请求的内存分配。该指令对性能影响最小，一般不应该使用。 ### reset\_timedout\_connection | - | 说明 | | ------- | ---------------------------------------------- | | **语法** | **reset\_timedout\_connection** `on` \| `off`; | | **默认** | reset\_timedout\_connection off; | | **上下文** | http、server、location | 启用或禁用重置超时连接。重置过程如下。在关闭一个套接字之前，`SO_LINGER` 选项超时值被设置为 0。当套接字关闭时，TCP RST 被发送到客户端，并且释放该套接字占用的所有内存。这有助于避免长时间持有一个缓冲区已经被填充 FIN\_WAIT1 状态的已关闭套接字。 应该注意，超时的 keep-alive 连接被正常关闭。 ### resolver | - | 说明 | | ------- | -------------------------------------------------- | | **语法** | **resolver** \`address ... \[valid=time] \[ipv6=on | | **默认** | —— | | **上下文** | http、server、location | 将用于解析 upstream 服务器名称的名称服务器配置进指定的地址，例如： ```nginx 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 地址。如果不想查找 IPv6 地址，则可以指定 `ipv6=off` 参数。 > 从 1.5.8 版本开始，支持将名称解析为 IPv6 地址。 默认情况下，nginx 使用响应的 TTL 值缓存回复。可选的 `valid` 参数可以覆盖它： ```nginx resolver 127.0.0.1 [:: 1]:5353 valid=30s; ``` > 在 1.1.9 版本之前，缓存时间是不能调整的，nginx 总是缓存 5 分钟的回复。 > 为了防止 DNS 欺骗，建议在安全的可信任本地网络中配置 DNS 服务器。 ### satisfy | - | 说明 | | ------- | --------------------------- | | **语法** | **satisfy** `all` \| `any`; | | **默认** | satisfy all; | | **上下文** | http、server、location | 如果所有（全部）或至少一个（任意一个） [ngx\_http\_access\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_access_module)、[ngx\_http\_auth\_basic\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_auth_basic_module)、[ngx\_http\_auth\_request\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_auth_request_module) 或 [ngx\_http\_auth\_jwt\_module](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_auth_jwt_module) 模块允许访问，则允许访问。 示例： ```nginx location / { satisfy any; allow 192.168.1.0/32; deny all; auth_basic "closed site"; auth_basic_user_file conf/htpasswd; } ``` ### send\_lowat | - | 说明 | | ------- | ----------------------- | | **语法** | **send\_lowat** `size`; | | **默认** | send\_lowat 0; | | **上下文** | http、server、location | 如果指令设置为非零值，nginx 将尝试通过使用 [kqueue](http://nginx.org/en/docs/events.html#kqueue) 方法的 `NOTE_LOWAT` 标志或`SO_SNDLOWAT` 套接字选项来最小化客户端套接字上的发送操作数。在这两种情况下都使用到了指定的 `size`。 该指令在 Linux、Solaris 和 Windows 上被忽略。 ### send\_timeout | - | 说明 | | ------- | ------------------------- | | **语法** | **send\_timeout** `time`; | | **默认** | send\_timeout 60s; | | **上下文** | http、server、location | 设置向客户端发送响应的超时时间。超时设置只限定在两次连续的写入操作之间，而不是用于整个响应的传输。如果客户端在此时间内没有收到任何内容，则连接将被关闭。 ### sendfile | - | 说明 | | ------- | ----------------------------------- | | **语法** | **sendfile** `on` \| `off`; | | **默认** | sendfile off; | | **上下文** | http、server、location、location 中的 if | 启用或禁用 `sendfile()`。 从 nginx 0.8.12 和 FreeBSD 5.2.1 开始，可以用 [aio](#aio) 来为 `sendfile()` 预加载数据： ```nginx location /video/ { sendfile on; tcp_nopush on; aio on; } ``` 在此配置中，使用 `SF_NODISKIO` 标志调用 `sendfile()`，使其不会阻塞磁盘 I/O，而是以报告数据不在内存中的方式代替。然后 nginx 通过读取一个字节来启动异步数据加载。在第一次读取时，FreeBSD 内核会将文件的第一个 128K 字节加载到内存中，但是下一次读取只能以 16K 块加载数据。可以使用 [read\_ahead](#read_ahead) 指令进行修改。 > 在 1.7.11 版本之前，可以使用 `aio sendfile` 来启用预加载。 ### sendfile\_max\_chunk | - | 说明 | | ------- | ------------------------------------- | | **语法** | \*\*sendfile\_max\_chunk \*\* `size`; | | **默认** | sendfile\_max\_chunk 0; | | **上下文** | http、server、location | 设置为非零值时，可限制单个 `sendfile()` 调用时传输的数据量。如果没有限制，一个快速连接可能会完全占用工作进程。 ### server | - | 说明 | | ------- | --------------------- | | **语法** | **server** `{ ... }`; | | **默认** | —— | | **上下文** | http | 设置虚拟服务器的配置。基于 IP（基于 IP 地址）和基于名称（基于 `Host` 请求头字段）的虚拟服务器之间没有明确的界限。相反，[listen](#listen) 指令描述应接受服务器连接的所有地址和端口，[server\_name](#server_name) 指令列出所有服务器名称。[如何处理请求](http://nginx.org/en/docs/http/request_processing.html)文档中提供了配置示例。 ### server\_name | - | 说明 | | ------- | ---------------------------- | | **语法** | **server\_name** `name ...`; | | **默认** | server\_name ""; | | **上下文** | server | 设置虚拟服务器名称，例如： ```nginx server { server_name example.com www.example.com; } ``` 第一个名字将成为主服务器名称。 服务器名称可以包含一个星号（`*`）以代替名称的第一部分或最后一部分： ```nginx server { server_name example.com *.example.com www.example.*; } ``` 这样的名称被称为通配符名称。 上面提到的前两个名字可以合并成一个： ```nginx server { server_name .example.com; } ``` 也可以在服务器名称中使用正则表达式，在名称前面加上波浪号（`〜`）： ```nginx server { server_name www.example.com ~^www\d+\.example\.com$; } ``` 正则表达式可以包含之后用于其他指令的捕获（0.7.40）： ```nginx server { server_name ~^(www\.)?(.+)$; location / { root /sites/$2; } } server { server_name _; location / { root /sites/default; } } ``` 在正则表达式中命名捕获创建变量（0.8.25），之后可在其他指令中使用： ```nginx server { server_name ~^(www\.)?(?.+)$; location / { root /sites/$domain; } } server { server_name _; location / { root /sites/default; } } ``` 如果指令参数设置为 `$hostname`（0.9.4），则将替换为机器的主机名。 也可以指定一个空的服务器名称（0.7.11）： ```nginx server { server_name www.example.com ""; } ``` 它允许这个服务器对给定的 address:port 对处理没有 `Host` 头的请求，而不是默认的服务器。这是默认设置。 > 在 0.8.48 之前，默认使用机器的主机名。 在按名称搜索虚拟服务器的过程中，如果名称与多个指定变体相匹配（例如，通配符名称和正则表达式匹配），将按照以下优先顺序选择第一个匹配变体： 1. 确切的名字 2. 以星号开头的最长通配符名称，例如 `*.example.com` 3. 以星号结尾的最长通配符名称，例如 `mail.*` 4. 第一个匹配的正则表达式（按照配置文件中的出现顺序） 服务器名称的详细描述在单独的[服务器名称](http://nginx.org/en/docs/http/server_names.html)文档中提供。 ### server\_name\_in\_redirect | - | 说明 | | ------- | ------------------------------- | | **语法** | **server\_name** `on` \| `off`; | | **默认** | server\_name\_in\_redirect off; | | **上下文** | http、server、location | 启用或禁用在由 nginx 发出的 [absolute](#absolute_redirect) 指令中使用由 [server\_name](#server_name) 指令指定的主服务器名称。当禁用主服务器名称时，将使用 `Host` 请求头字段中的名称。如果此字段不存在，则使用服务器的 IP 地址。 重定向中使用端口由 [port\_in\_redirect](#port_in_redirect) 指令控制。 ### server\_names\_hash\_bucket\_size | - | 说明 | | ------- | --------------------------------------------- | | **语法** | **server\_names\_hash\_bucket\_size** `size`; | | **默认** | server\_names\_hash\_bucket\_size 32 | | **上下文** | http | 设置服务器名称哈希表的存储桶大小。默认值取决于处理器缓存行的大小。设置哈希表的细节在单独的[文档](http://nginx.org/en/docs/hash.html)中提供。 ### server\_names\_hash\_max\_size | - | 说明 | | ------- | ------------------------------------------ | | **语法** | **server\_names\_hash\_max\_size** `size`; | | **默认** | server\_names\_hash\_max\_size 512; | | **上下文** | http | 设置服务器名称哈希表的最大大小。设置哈希表的细节在单独的[文档](https://github.com/DocsHome/nginx-docs/blob/master/%E6%A8%A1%E5%9D%97%E5%8F%82%E8%80%83/http/\(http:/nginx.org/en/docs/hash.html\))中提供。 ### server\_tokens | - | 说明 | | ------- | -------------------------------------------------------- | | **语法** | **server\_tokens** `on` \| `off` \| `build` \| `string`; | | **默认** | server\_tokens on; | | **上下文** | http、server、location | 在错误页面和 `Server` 响应头字段中启用或禁用发送 nginx 版本。 `build` 参数（1.11.10）能够发送构建名称以及 nginx 版本。 此外，作为我们的[商业订阅](http://nginx.com/products/?_ga=2.14041591.1300915338.1513355851-1890203964.1497190280)的一部分，从1.9.13 版本开始，可以使用带有变量的字符串显式设置错误页面上的签名和 `Server` 响应头字段值。指定空字符串将禁用 `Server` 字段的发送。 ### tcp\_nodelay | - | 说明 | | ------- | ------------------------------- | | **语法** | **tcp\_nodelay** `on` \| `off`; | | **默认** | tcp\_nodelay on; | | **上下文** | http、server、location | 启用或禁用 `TCP_NODELAY` 选项的使用。该选项仅在连接转换到 keep-alive 状态时启用。 ### tcp\_nopush | - | 说明 | | ------- | ------------------------------ | | **语法** | **tcp\_nopush** `on` \| `off`; | | **默认** | tcp\_nopush off; | | **上下文** | http、server、location | 启用或禁用在 FreeBSD 上使用 `TCP_NOPUSH` 套接字选项或在 Linux 上使用 `TCP_CORK` 套接字选项。这些选项只有在使用 [sendfile](#sendfile) 时才能使用。启用该选项将允许： * 在 Linux 和 FreeBSD 4 上，在同一包中可发送响应头和文件开头。 * 以完整包的方式发送一个文件 ### try\_files | - | 说明 | | ------- | ------------------------------------------------------------------------------------------------------------------------- | | **语法** |

try\_files file ... uri;
try\_files file ... =code;

| | **默认** | —— | | **上下文** | server、location | 以指定顺序检查文件是否存在，并使用第一个找到的文件进行请求处理。处理将在当前上下文中执行。指向文件的路径根据 [root](#root) 和 [alias](#alias) 指令从 `file` 参数构造。可以通过在名称末尾指定斜线来检查目录是否存在，例如，`$URI/`。如果找不到任何文件，则内部重定向将指向最后一个参数中指定的 `uri`。例如： ```nginx location /images/ { try_files $uri /images/default.gif; } location = /images/default.gif { expires 30s; } ``` 最后一个参数也可以指向一个命名的 location ，如以下示例。从 0.7.51 版本开始，最后一个参数也可以是一个 `code`： ```nginx location / { try_files $uri $uri/index.html $uri.html =404; } ``` 代理 Mongrel 示例： ```nginx location / { try_files /system/maintenance.html $uri $uri/index.html $uri.html @mongrel; } location @mongrel { proxy_pass http://mongrel; } ``` Drupal/FastCGI 示例： ```nginx 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 } ``` 在以下示例中 ```nginx location / { try_files $uri $uri/ @drupal; } ``` try\_files 指令相当于 ```nginx location / { error_page 404 = @drupal; log_not_found off; } ``` 还有一个示例 ```nginx location ~ \.php$ { try_files $uri @drupal; fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; ... } ``` 在将请求传递给 FastCGI 服务器之前，try\_files 将检查 PHP 文件是否存在。 Wordpress 与 Joomla 示例： ```nginx 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 | - | 说明 | | ------- | --------------------------------------------------------------------------------------- | | **语法** | **types** `{ ... }`; | | **默认** |

types {
text/html html;
image/gif gif;
image/jpeg jpg;
}

| | **上下文** | http、server、location | 将文件扩展名映射到响应的 MIME 类型。扩展名不区分大小写。多个扩展名可以映射到同个类型，例如： ```nginx types { application/octet-stream bin exe dll; application/octet-stream deb; application/octet-stream dmg; } ``` `conf/mime.types` 是随 nginx 分发的一个较完整的映射配置文件。 要指定一个 location 的所有请求都返回 `application/octet-stream` MIME 类型，可以使用以下配置： ```nginx location /download/ { types { } default_type application/octet-stream; } ``` ### types\_hash\_bucket\_size | - | 说明 | | ------- | ------------------------------------- | | **语法** | **types\_hash\_bucket\_size** `size`; | | **默认** | types\_hash\_bucket\_size 64; | | **上下文** | http、server、location | 设置类型哈希表桶大小。设置哈希表的细节在单独的[文档](http://nginx.org/en/docs/hash.html)中有提供。 > 在版 1.5.13 本之前，默认值取决于处理器缓存行的大小。 ### types\_hash\_max\_size | - | 说明 | | ------- | ---------------------------------- | | **语法** | **types\_hash\_max\_size** `size`; | | **默认** | types\_hash\_max\_size 1024; | | **上下文** | http、server、location | 设置类型哈希表的最大大小。设置哈希表的细节在单独的[文档](http://nginx.org/en/docs/hash.html)中有提供。 ### underscores\_in\_headers | - | 说明 | | ------- | ------------------------------------------- | | **语法** | **underscores\_in\_headers** `on` \| `off`; | | **默认** | underscores\_in\_headers off; | | **上下文** | http、server | 启用或禁用在客户端请求头字段中使用下划线。当禁用下划线时，名称中包含下划线的请求头字段将被标记为无效，并受制于 [ignore\_invalid\_headers](#ignore_invalid_headers) 指令。 如果该指令是在 [server](#server) 级别指定，则仅在 server 是默认 server 时才使用该指令。指定的值也适用于监听相同地址和端口的所有虚拟服务器。 ### variables\_hash\_bucket\_size | - | 说明 | | ------- | ----------------------------------------- | | **语法** | **variables\_hash\_bucket\_size** `size`; | | **默认** | variables\_hash\_bucket\_size size; | | **上下文** | http | 设置变量哈希表桶大小。设置哈希表的细节在单独的[文档](http://nginx.org/en/docs/hash.html)中有提供。 ### variables\_hash\_max\_size | - | 说明 | | ------- | -------------------------------------- | | **语法** | **variables\_hash\_max\_size** `size`; | | **默认** | variables\_hash\_max\_size 1024; | | **上下文** | http | 设置变量哈哈希表的最大大小。设置哈希表的细节在单独的[文档](http://nginx.org/en/docs/hash.html)中有提供。 > 在 1.5.13 版本之前，默认值是 512。 ## 内嵌变量 `ngx_http_core_module` 模块支持嵌入式变量名称与 Apache 服务器变量匹配。首先，这些是出现在客户端请求头字段的变量，例如 `$http_user_agent`、`$http_cookie` 等等。还有其他变量： * `$arg_name` 请求行中的 `name` 参数 * `$args` 请求行中的参数 * `$binary_remote_addr` 客户端地址以二进制形式表示，值的长度对于 IPv4 地址总是 4 个字节，对于 IPv6 地址总是 16 个字节 * `$body_bytes_sent` 发送到客户端的字节数，不包括响应头。此变量与 `mod_log_config` Apache 模块的 `％B` 参数兼容 * `$bytes_sent` 发送到客户端的字节数（1.3.8、1.2.5） * $connection 连接序列号（1.3.8、1.2.5） * `$connection_requests` 当前通过连接请求的请求数（1.3.8、1.2.5） * `$connect_length` `Content-Length` 请求头字段 * `$content_type` `Content-Type` 请求头字段 * `$cookie_name` 名称为 `name` 的 cookie * `$document_root` 根目录或别名指令的当前请求的值 * `$document_uri` 与 `$uri` 相同 * `$host` 按照以下优先顺序：来自请求行的主机名，来自 `Host` 请求头字段的主机名，或与请求匹配的服务器名 * `$hostname` 主机名 * `$http_name` 任意请求头字段,变量名称的最后一部分是将字段名称转换为小写，并用破折号替换为下划线 * `$https` 如果连接以 SSL 模式运行，则为 `on`，否则为空字符串 * `$is_args` 如果请求行有参数则为 `?`，否则为空字符串 * `$limit_rate` 设置这个变量可以实现响应速率限制，见 [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](#listen) 指令中设置 `proxy_protocol` 参数，必须先启用 PROXY 协议。 * `$proxy_protocol_port` PROXY 协议头中的客户端口，否则为空字符串（1.11.0） 要在 [listen](#listen) 指令中设置 `proxy_protocol` 参数，必须先启用 PROXY 协议。 * `$query_string` 与 `$args` 相同 * `$realpath_root` 与当前请求的 [root](#root) 或 [alias](#alias) 指令值相对应的绝对路径名，所有符号链接都将解析为实际路径 * `$remote_addr` 客户端地址 * `$remote_port` 客户端端口 * `$remote_user` 基本身份验证提供的用户名 * `$request` 完整的原始请求行 * `$request_body` 请求正文 当请求正文被读取到[内存缓冲区](#client_body_buffer_size)时，变量的值在由[proxy\_pass](https://github.com/DocsHome/nginx-docs/blob/master/%E6%A8%A1%E5%9D%97%E5%8F%82%E8%80%83/http/gx_http_proxy_module.md#proxy_pass)、[fastcgi\_pass](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_fastcgi_module#fastcgi_pass)、[uwsgi\_pass](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_uwsgi_module#uwsgi_pass) 和 [scgi\_pass](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_scgi_module#scgi_pass) 指令处理的 location 中可用。 * `$request_body_file` 带有请求正文的临时文件的名称 在处理结束时，文件需要被删除。想始终将请求主体写入文件中，需要启用 [client\_body\_in\_file\_only](#client_body_in_file_only)。当临时文件的名称在代理请求中或在向 FastCGI/uwsgi/SCGI 服务器的请求中传递时，应该分别通过 [proxy\_pass\_request\_body off](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_proxy_module#proxy_pass_request_body)、[fastcgi\_pass\_request\_body off](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_fastcgi_module#fastcgi_pass_request_body)、[uwsgi\_pass\_request\_body off](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_uwsgi_module#uwsgi_pass_request_body) 或 [scgi\_pass\_request\_body off](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/ngx_http_scgi_module#scgi_pass_request_body) 指令禁用传递请求正文。 * `$request_completion` 如果请求已经完成，则返回 `OK`，否则返回空字符串 * `$request_filename` 当前请求的文件路径，基于 [root](#root) 或 [alias](#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](#listen) 指令必须指定地址并使用 `bind` 参数。 * `$server_name` 接受请求的服务器名称 * `$server_port` 接受请求的服务器端口 * `$server_protocol` 请求协议，通常为 `HTTP/1.0`、`HTTP/1.1` 或 [HTTP/2.0](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_v2_module) * `$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` 通用日志格式（Common Log Format）中的本地时间（1.3.12、1.2.7） * `$uri` [规范化](#location)过的当前请求 URI `$uri` 的值可能在请求期间会改变 ## 原文档