# HTTP 模块
核心 HTTP 模块实现了 HTTP 服务器的基本功能：包括定义服务器块、配置用于请求路由的位置、提供静态文件和控制访问、配置重定向、支持 keep-alive 连接以及管理请求和响应标头。
本节中的其他模块扩展了此功能，允许您针对各种场景和需求灵活配置和优化 HTTP 服务器。
## 指令
### absolute_redirect
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `absolute_redirect` `on` | `off`; |
|--------------------------------------------------------------------------------------|-------------------------------------|
| 默认值 | `absolute_redirect on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
如果禁用,Angie 发出的重定向将是相对的。
另请参阅 [server_name_in_redirect](#server-name-in-redirect) 和 [port_in_redirect](#port-in-redirect) 指令。
### aio
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `aio` `on` | `off` | `threads` [=pool]; |
|--------------------------------------------------------------------------------------|-------------------------------------------|
| 默认值 | `aio off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
在 FreeBSD 和 Linux 上启用或禁用异步文件 I/O (AIO) 的使用:
```nginx
location /video/ {
aio on;
output_buffers 1 64k;
}
```
在 FreeBSD 上,从 FreeBSD 4.3 开始可以使用 AIO。在 FreeBSD 11.0 之前,AIO 可以静态链接到内核中:
```nginx
options VFS_AIO
```
或作为内核可加载模块动态加载:
```nginx
kldload aio
```
在 Linux 上,从内核版本 2.6.22 开始可以使用 AIO。此外,还需要启用 [directio](#directio),否则读取将会阻塞:
```nginx
location /video/ {
aio on;
directio 512;
output_buffers 1 128k;
}
```
在 Linux 上,:ref:directio 只能用于读取按 512 字节边界对齐的块(对于 XFS 为 4K)。文件的未对齐末尾以阻塞模式读取。对于字节范围请求和非从文件开头开始的 FLV 请求也是如此:在文件开头和末尾读取未对齐的数据将会阻塞。
当在 Linux 上同时启用 AIO 和 [sendfile](#sendfile) 时,对于大于或等于 [directio](#directio) 指令中指定大小的文件使用 AIO,而对于较小的文件或禁用 [directio](#directio) 时使用 [sendfile](#sendfile):
```nginx
location /video/ {
sendfile on;
aio on;
directio 8m;
}
```
最后,可以使用多线程读取和 [发送](#sendfile) 文件,而不会阻塞工作进程:
```nginx
location /video/ {
sendfile on;
aio threads;
}
```
读取和发送文件操作被卸载到指定 [池](https://cn.angie.software//angie/docs/configuration/modules/core.md#thread-pool) 的线程。如果省略池名称,则使用名为 "default" 的池。池名称也可以使用变量设置:
```nginx
aio threads=pool$disk;
```
使用 `aio on` 需要使用 `--with-file-aio` 配置参数进行构建。使用 `aio threads` 需要使用 `--with-threads` 参数进行构建。
目前,多线程仅与 [epoll](https://cn.angie.software//angie/docs/configuration/processing.md#epoll)、[kqueue](https://cn.angie.software//angie/docs/configuration/processing.md#kqueue) 和 [eventport](https://cn.angie.software//angie/docs/configuration/processing.md#eventport) 方法兼容。多线程发送文件仅在 Linux 上受支持。
另请参阅 [sendfile](#sendfile) 指令。
### aio_write
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `aio_write` `on` | `off`; |
|--------------------------------------------------------------------------------------|-----------------------------|
| 默认值 | `aio_write off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
如果启用了 [aio](#aio),指定是否将其用于写入文件。目前,这仅在使用 `aio threads` 时有效,并且仅限于写入包含从代理服务器接收的数据的临时文件。
### alias
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `alias` path; |
|--------------------------------------------------------------------------------------|-----------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location |
为指定的位置定义替换路径。例如,使用以下配置:
```nginx
location /i/ {
alias /data/w3/images/;
}
```
对于 `/i/top.gif` 的请求,将发送文件 /data/w3/images/top.gif。
path 值可以包含变量,但不包括 [$document_root](#v-document-root) 和 [$realpath_root](#v-realpath-root)。
如果在使用正则表达式定义的位置内使用 `alias`,则该正则表达式应包含捕获组,并且 `alias` 应引用这些捕获组,例如:
```nginx
location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
alias /data/w3/images/$1;
}
```
当位置匹配指令值的最后部分时:
```nginx
location /images/ {
alias /data/w3/images/;
}
```
最好使用 [root](#root) 指令:
```nginx
location /images/ {
root /data/w3;
}
```
### auth_delay
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `auth_delay` time; |
|--------------------------------------------------------------------------------------|------------------------|
| 默认值 | `auth_delay 0s;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
延迟处理返回 401 响应代码的未授权请求,以防止在通过 [密码](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) 或 [子请求结果](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) 限制访问时的时序攻击。
### auto_redirect
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `auto_redirect` [`on` | `off` | `default`]; |
|--------------------------------------------------------------------------------------|-----------------------------------------------|
| 默认值 | `auto_redirect default;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
控制当前缀位置以斜杠结尾时的 [重定向](#location-redirect) 行为:
```nginx
location /prefix/ {
auto_redirect on;
}
```
在这里,对 `/prefix` 的请求会导致重定向到 `/prefix/`。
值 `on` 显式启用重定向,而 `off` 禁用它。当设置为 `default` 时,仅当位置使用 [api](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#a-api)、[proxy_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass)、[fastcgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass)、[uwsgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass)、[scgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass)、[memcached_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-pass) 或 [grpc_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-pass) 处理请求时才启用重定向。
### chunked_transfer_encoding
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `chunked_transfer_encoding` `on` | `off`; |
|--------------------------------------------------------------------------------------|---------------------------------------------|
| 默认值 | `chunked_transfer_encoding on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
允许在 HTTP/1.1 中禁用分块传输编码。当使用的软件尽管标准要求但不支持分块编码时,这可能会派上用场。
### client
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client` { ... } |
|--------------------------------------------------------------------------------------|--------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
创建一个特殊的 `client` 上下文,用于处理 Angie 自行执行的内部 HTTP 请求,而无需外部客户端参与。
`client` 上下文将来自各种 Angie 模块的服务流量与用户流量隔离,允许对其进行额外控制。在此上下文中,只能定义命名位置(带有 `@` 前缀);它们无法被外部 HTTP 请求访问,只能通过内部服务器机制以编程方式调用。
`client` 上下文用于:
- 在 [ACME](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) 模块中通过预定义的 `location @acme` 向证书颁发机构发送请求,可以使用 [代理](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) 模块的指令进行额外配置;
- 在 [Docker](https://cn.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker) 模块中通过预定义的 `location @docker_events` 和 `@docker_containers` 向 Docker API 发送请求,可以使用 [代理](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) 模块的指令进行额外配置;
- 通过 [upstream_probe (PRO)](https://cn.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe) 对代理服务器进行健康探测;
- 在流 [Upstream](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream) 模块中使用 `remote_action` 的 [sticky learn](https://cn.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-sticky) 模式。
支持多个 `client` 块允许在每个块内为多个 `location` 块分组通用设置,这有助于避免配置重复。
在每个 `client` 块中指定的指令仅由在其中显式声明的 `location` 块继承。特别是,这就是为什么它们不会影响隐式使用 `client` 块进行出站请求的其他模块的配置(例如 [ACME](https://cn.angie.software//angie/docs/configuration/modules/http/http_acme.md#http-acme) 或 [Docker](https://cn.angie.software//angie/docs/configuration/modules/http/http_docker.md#http-docker))。
使用多个 `client` 块并继承设置的示例:
```nginx
client {
proxy_set_header Host docker.example.com;
proxy_set_header Authorization "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==";
location @docker_events {
}
location @docker_containers {
}
}
client {
proxy_method GET;
proxy_set_header Host backend.example.com;
proxy_set_header X-Real-IP $remote_addr;
location @health_check {
proxy_pass http://upstream-server/health;
}
}
```
#### NOTE
这里允许使用与常规 `location` 块中相同的指令,
但实际上只有内容处理器
(如 [js_content](https://cn.angie.software//angie/docs/installation/external-modules/http_js.md#js-content) 或 [autoindex](https://cn.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#id3))
和变量处理器(如 [map](https://cn.angie.software//angie/docs/configuration/modules/http/http_map.md#id3)),
以及自身生成请求的指令
(如 `upstream_probe`)才会生效。
在其他 [请求处理阶段](https://cn.angie.software//angie/docs/configuration/processing.md#http-sessions) 操作的指令
(如 [limit_req](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#limit-req)、[auth_request](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id3)、
[try_files](#try-files)、图像过滤器、XSLT 等)
在这里不起作用。
### client_body_buffer_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_buffer_size` size; |
|--------------------------------------------------------------------------------------|-----------------------------------|
| 默认值 | `client_body_buffer_size 8k|16k;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置读取客户端请求体的缓冲区大小。如果请求体大于缓冲区,则将整个请求体或仅其部分写入 [临时文件](#client-body-temp-path)。默认情况下,缓冲区大小等于两个内存页。在 x86、其他 32 位平台和 x86-64 上,这是 8K。在其他 64 位平台上,通常是 16K。
### client_body_in_file_only
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_in_file_only` `on` | `clean` | `off`; |
|--------------------------------------------------------------------------------------|------------------------------------------------------|
| 默认值 | `client_body_in_file_only off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
确定是否将整个客户端请求体保存到文件中。此指令可在调试期间使用,或在使用 [$request_body_file](#v-request-body-file) 变量或 [Perl](https://cn.angie.software//angie/docs/configuration/modules/http/http_perl.md#http-perl) 模块的 [$r->request_body_file](https://cn.angie.software//angie/docs/configuration/modules/http/http_perl.md#p-r-request-body-file) 方法时使用。
| `on` | 请求处理后不删除临时文件 |
|---------|------------------|
| `clean` | 允许删除请求处理后留下的临时文件 |
### client_body_in_single_buffer
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_in_single_buffer` `on` | `off`; |
|--------------------------------------------------------------------------------------|------------------------------------------------|
| 默认值 | `client_body_in_single_buffer off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
确定是否将整个客户端请求体保存在单个缓冲区中。建议在使用 [$request_body](#v-request-body) 变量时使用此指令,以减少涉及的复制操作数量。
### client_body_temp_path
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_temp_path` path [level1 [level2 [level3]]]; |
|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 默认值 | `client_body_temp_path client_body_temp;`
(路径取决于 [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-client-body-temp-path`) |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
定义用于存储客户端请求体临时文件的目录。在指定目录下最多可以使用三级子目录层次结构。例如,在以下配置中
```nginx
client_body_temp_path /spool/angie/client_temp 1 2;
```
临时文件的路径可能如下所示:
```nginx
/spool/angie/client_temp/7/45/00000123457
```
### client_body_timeout
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_body_timeout` time; |
|--------------------------------------------------------------------------------------|-------------------------------|
| 默认值 | `client_body_timeout 60s;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
定义读取客户端请求体的超时时间。超时仅针对两次连续读取操作之间的时间段设置,而不是针对整个请求体的传输。如果客户端在此时间内未传输任何内容,则请求将以 408 (Request Time-out) 错误终止。
### client_header_buffer_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_header_buffer_size` size; |
|--------------------------------------------------------------------------------------|-------------------------------------|
| 默认值 | `client_header_buffer_size 1k;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
设置读取客户端请求头的缓冲区大小。对于大多数请求,1K 字节的缓冲区就足够了。但是,如果请求包含长 cookie,或来自 WAP 客户端,则可能无法容纳在 1K 中。如果请求行或请求头字段无法容纳在此缓冲区中,则会分配由 [large_client_header_buffers](#large-client-header-buffers) 指令配置的更大缓冲区。
如果在 [server](#server) 级别指定该指令,则可以使用默认服务器的值。详情请参阅 [虚拟服务器选择](https://cn.angie.software//angie/docs/configuration/processing.md#request-processing) 部分。
### client_header_timeout
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_header_timeout` time; |
|--------------------------------------------------------------------------------------|---------------------------------|
| 默认值 | `client_header_timeout 60s;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
定义读取客户端请求头的超时时间。如果客户端在此时间内未传输整个请求头,则请求将以 408 (Request Time-out) 错误终止。
### client_max_body_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `client_max_body_size` size; |
|--------------------------------------------------------------------------------------|--------------------------------|
| 默认值 | `client_max_body_size 1m;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置客户端请求体的最大允许大小。如果请求中的大小超过配置的值,则向客户端返回 413 (Request Entity Too Large) 错误。请注意,浏览器无法正确显示此错误。
| `0` | 禁用检查客户端请求体大小 |
|-------|----------------|
### connection_pool_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `connection_pool_size` size; |
|--------------------------------------------------------------------------------------|-------------------------------------|
| 默认值 | `connection_pool_size 256` | `512;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
允许精确调整每个连接的内存分配。此指令对性能的影响很小,通常不应使用。默认情况下:
| `256` (字节) | 在 32 位平台上 |
|--------------|-------------|
| `512` (字节) | 在 64 位平台上 |
### default_type
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `default_type` mime-type; |
|--------------------------------------------------------------------------------------|-----------------------------|
| 默认值 | `default_type text/plain;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
定义响应的默认 MIME 类型。文件扩展名到 MIME 类型的映射可以使用 [types](#types) 指令设置。
### directio
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `directio` size | `off`; |
|--------------------------------------------------------------------------------------|----------------------------|
| 默认值 | `directio off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
在读取大于或等于指定大小的文件时,启用 `O_DIRECT` 标志(FreeBSD、Linux)、`F_NOCACHE` 标志(macOS)或 `directio()` 函数(Solaris)的使用。该指令会自动禁用给定请求的 [sendfile](#sendfile) 使用。建议用于提供大文件:
```nginx
directio 4m;
```
或在 Linux 上使用 [aio](#aio) 时。
### directio_alignment
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `directio_alignment` size; |
|--------------------------------------------------------------------------------------|------------------------------|
| 默认值 | `directio_alignment 512;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置 [directio](#directio) 的对齐方式。在大多数情况下,512 字节对齐就足够了。但是,在 Linux 下使用 XFS 时,需要将其增加到 4K。
### disable_symlinks
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `disable_symlinks` `off`;
`disable_symlinks` `on` | `if_not_owner` [`from=`part]; |
|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| 默认值 | `disable_symlinks off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
确定在打开文件时应如何处理符号链接:
| `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。
#### WARNING
`on` 和 `if_not_owner` 参数会增加处理开销。
在不支持仅为搜索而打开目录的系统上,使用这些参数需要工作进程对所有被检查的目录具有读取权限。
#### NOTE
[AutoIndex](https://cn.angie.software//angie/docs/configuration/modules/http/http_autoindex.md#http-autoindex)、[Random Index](https://cn.angie.software//angie/docs/configuration/modules/http/http_random_index.md#http-random-index) 和 [DAV](https://cn.angie.software//angie/docs/configuration/modules/http/http_dav.md#http-dav) 模块目前忽略此指令。
### early_hints
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `early_hints` string ...; |
|--------------------------------------------------------------------------------------|-----------------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
定义将 "103 Early Hints" 响应传递给客户端的条件。如果字符串参数的至少一个值不为空且不等于 `0`,则将传递响应:
```nginx
map $http_sec_fetch_mode $early_hints {
navigate $http2$http3;
}
server {
...
location / {
early_hints $early_hints;
proxy_pass http://example.com;
}
}
```
### error_page
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `error_page` code ... [=[response]] uri; |
|--------------------------------------------------------------------------------------|--------------------------------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location |
定义针对指定错误显示的 URI。uri 值可以使用变量。
示例:
```nginx
error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;
```
这会导致内部重定向到指定的 uri,并将客户端请求方法更改为 "GET"(对于除 "GET" 和 "HEAD" 之外的所有方法)。
此外,可以使用类似 `=response` 的语法将响应代码更改为另一个代码,例如:
```nginx
error_page 404 =200 /empty.gif;
```
如果错误响应由代理服务器或 FastCGI/uwsgi/SCGI/gRPC 服务器处理,并且该服务器可能返回不同的响应代码(例如 200、302、401 或 404),则可以传递它返回的代码:
```nginx
error_page 404 = /404.php;
```
如果在内部重定向期间不需要更改 URI 和方法,可以将错误处理传递到命名的 `location`:
```nginx
location / {
error_page 404 = @fallback;
}
location @fallback {
proxy_pass http://backend;
}
```
#### NOTE
如果在处理 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)。
### etag
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `etag` `on` | `off`; |
|--------------------------------------------------------------------------------------|------------------------|
| 默认值 | `etag on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用为静态资源自动生成 `ETag` 响应头字段。
### http
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `http` { ... } |
|--------------------------------------------------------------------------------------|------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | main |
提供配置文件上下文,在其中指定 HTTP 服务器指令。
### if_modified_since
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `if_modified_since` `off` | `exact` | `before`; |
|--------------------------------------------------------------------------------------|---------------------------------------------------|
| 默认值 | `if_modified_since exact;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
指定如何将响应的修改时间与 `If-Modified-Since` 请求头字段中的时间进行比较:
| `off` | 响应始终被视为已修改 |
|----------|--------------------------------------------|
| `exact` | 精确匹配 |
| `before` | 响应的修改时间小于或等于 `If-Modified-Since` 请求头字段中的时间 |
### ignore_invalid_headers
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ignore_invalid_headers` `on` | `off`; |
|--------------------------------------------------------------------------------------|------------------------------------------|
| 默认值 | `ignore_invalid_headers on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
控制 Angie 是否忽略具有无效名称的头字段。有效名称由英文字母、数字、连字符组成,可能还包括下划线(由 [underscores_in_headers](#underscores-in-headers) 指令控制)。
如果在 [server](#server) 级别指定该指令,则可以使用默认服务器的值。
### internal
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `internal;` |
|--------------------------------------------------------------------------------------|---------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location |
指定给定的 `location` 只能用于内部请求。对于外部请求,将向客户端返回 404 (Not Found) 错误。内部请求包括以下几种:
* 由 [error_page](#error-page)、[index](https://cn.angie.software//angie/docs/configuration/modules/http/http_index.md#id3)、[random_index](https://cn.angie.software//angie/docs/configuration/modules/http/http_random_index.md#id3) 和 [try_files](#try-files) 指令重定向的请求;
* 由上游服务器的 `X-Accel-Redirect` 响应头字段重定向的请求;
* 由 [SSI](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssi.md#http-ssi) 模块的 `include virtual` 命令、[Addition](https://cn.angie.software//angie/docs/configuration/modules/http/http_addition.md#http-addition) 模块指令以及 [auth_request](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#id3) 和 [mirror](https://cn.angie.software//angie/docs/configuration/modules/http/http_mirror.md#id3) 指令形成的子请求;
* 由 [rewrite](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) 指令更改的请求。
示例:
```nginx
error_page 404 /404.html;
location = /404.html {
internal;
}
```
由于 404 错误是在带有 `internal` 指令的 `location` 上下文中返回的,外部请求可以重定向到不同的 location。这允许对外部和内部请求使用相同的前缀,但进行不同的处理,例如:
```nginx
location /path {
internal;
error_page 404 =@external;
proxy_pass https://internal;
}
location @external {
proxy_pass https://external;
}
```
在这里,外部请求 `GET /path` 将被代理到
`https://external/path`,而相同的内部请求将被代理到
`https://internal/path`。
#### NOTE
为了防止错误配置可能导致的循环,内部重定向的次数限制为十次。当达到此限制时,将返回 500 (Internal Server Error) 错误。在这种情况下,可以在错误日志中看到 `rewrite or internal redirection cycle` 消息。
### keepalive_disable
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_disable` `none` | browser ...; |
|--------------------------------------------------------------------------------------|---------------------------------------------|
| 默认值 | `keepalive_disable msie6;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
禁用与行为异常的浏览器的保持连接。browser 参数指定将受影响的浏览器。
| `none` | 对所有浏览器启用保持连接 |
|----------|-----------------------------------------------------|
| `msie6` | 一旦收到 POST 请求,禁用与旧版本 MSIE 的保持连接 |
| `safari` | 禁用与 macOS 和类 macOS 操作系统上的 Safari 和类 Safari 浏览器的保持连接 |
### keepalive_requests
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_requests` number; |
|--------------------------------------------------------------------------------------|--------------------------------|
| 默认值 | `keepalive_requests 1000;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置通过一个保持连接可以处理的最大请求数。在达到最大请求数后,连接将被关闭。
定期关闭连接对于释放每个连接的内存分配是必要的。因此,使用过高的最大请求数可能会导致过度的内存使用,不建议这样做。
### keepalive_time
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_time` time; |
|--------------------------------------------------------------------------------------|--------------------------|
| 默认值 | `keepalive_time 1h;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
限制通过一个保持连接处理请求的最长时间。达到此时间后,连接将在后续请求处理完成后关闭。
### keepalive_timeout
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `keepalive_timeout` timeout [header_timeout]; |
|--------------------------------------------------------------------------------------|-------------------------------------------------|
| 默认值 | `keepalive_timeout 75s;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
| timeout | 设置保持连接的客户端连接在服务器端保持打开的超时时间 |
|-----------|------------------------------|
| `0` | 禁用保持连接的客户端连接 |
第二个 *可选* 参数在响应中设置 `Keep‑Alive: timeout=time` 头字段的值。这两个参数可以不同。
`Keep-Alive: timeout=time` 头字段被 Mozilla 和 Konqueror 识别。MSIE 会在大约 60 秒后自行关闭保持连接。
### large_client_header_buffers
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `large_client_header_buffers` number size; |
|--------------------------------------------------------------------------------------|----------------------------------------------|
| 默认值 | `large_client_header_buffers 4 8k;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
设置用于读取大型客户端请求头的缓冲区的最大数量和大小。请求行不能超过一个缓冲区的大小,否则将向客户端返回 414 (Request-URI Too Large) 错误。请求头字段也不能超过一个缓冲区的大小,否则将向客户端返回 400 (Bad Request) 错误。缓冲区仅在需要时分配。默认情况下,缓冲区大小等于 8K 字节。如果在请求处理结束后连接转换为保持连接状态,这些缓冲区将被释放。
如果在 [server](#server) 级别指定该指令,则可以使用默认服务器的值。
### limit_except
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_except` method1 [method2...] { ... }; |
|--------------------------------------------------------------------------------------|------------------------------------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | location |
限制 location 内允许的 HTTP 方法。method 参数可以是以下之一:`GET`、`HEAD`、`POST`、`PUT`、`DELETE`、`MKCOL`、`COPY`、`MOVE`、`OPTIONS`、`PROPFIND`、`PROPPATCH`、`LOCK`、`UNLOCK` 或 `PATCH`。允许 `GET` 方法也会使 `HEAD` 方法被允许。可以使用 [Access](https://cn.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access) 和 [Auth Basic](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) 模块指令限制对其他方法的访问:
```nginx
limit_except GET {
allow 192.168.1.0/32;
deny all;
}
```
#### NOTE
此示例中的限制适用于 **除** `GET` 和 `HEAD` **之外** 的所有方法。
### limit_rate
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_rate` rate; |
|--------------------------------------------------------------------------------------|----------------------------------------|
| 默认值 | `limit_rate 0;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location |
限制向客户端传输响应的速率。速率以每秒字节数指定。零值禁用速率限制。限制是针对每个请求设置的,因此如果客户端同时打开两个连接,总速率将是指定限制的两倍。
参数值可以包含变量。在需要根据特定条件限制速率的情况下,这可能很有用:
```nginx
map $slow $rate {
1 4k;
2 8k;
}
limit_rate $rate;
```
速率限制也可以在 [$limit_rate](#v-limit-rate) 变量中设置,但不建议使用此方法:
```nginx
server {
if ($slow) {
set $limit_rate 4k;
}
}
```
速率限制也可以在代理服务器响应的 `X-Accel-Limit-Rate` 头字段中设置。可以使用 [proxy_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-ignore-headers)、[fastcgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-ignore-headers)、[uwsgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-ignore-headers) 和 [scgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-ignore-headers) 指令禁用此功能。
### limit_rate_after
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `limit_rate_after` size; |
|--------------------------------------------------------------------------------------|----------------------------------------|
| 默认值 | `limit_rate_after 0;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location |
设置初始数量,在此之后向客户端传输响应的速率将受到限制。参数值可以包含变量。
示例:
```nginx
location /flv/ {
flv;
limit_rate_after 500k;
limit_rate 50k;
}
```
### lingering_close
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_close` `on` | `always` | `off`; |
|--------------------------------------------------------------------------------------|----------------------------------------------|
| 默认值 | `lingering_close on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
控制 Angie 如何关闭客户端连接。
| `on` | Angie 将 [等待](#lingering-timeout) 并 [处理](#lingering-time) 来自客户端的额外数据,然后完全关闭连接,但仅当启发式方法表明客户端可能正在发送更多数据时。 |
|----------|----------------------------------------------------------------------------------------------------------|
| `always` | Angie 将始终等待并处理额外的客户端数据。 |
| `off` | Angie 不会等待更多数据,将立即关闭连接。此行为会破坏协议,在正常情况下不应使用。 |
要控制 HTTP/2 连接的关闭,必须在 [server](#server) 级别指定该指令。
### lingering_time
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_time` time; |
|--------------------------------------------------------------------------------------|--------------------------|
| 默认值 | `lingering_time 30s;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
当 [lingering_close](#lingering-close) 生效时,此指令指定 Angie 处理(读取并忽略)来自客户端的额外数据的最长时间。在此之后,连接将被关闭,即使还有更多数据。
### lingering_timeout
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `lingering_timeout` time; |
|--------------------------------------------------------------------------------------|-----------------------------|
| 默认值 | `lingering_timeout 5s;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
当 [lingering_close](#lingering-close) 生效时,此指令指定等待更多客户端数据到达的最长等待时间。如果在此时间内未收到数据,连接将被关闭。否则,数据将被读取并忽略,Angie 再次开始等待更多数据。"等待-读取-忽略"循环会重复,但不会超过 [lingering_time](#lingering-time) 指令指定的时间。
在优雅关闭期间,客户端保持连接仅在空闲时间至少达到 `lingering_timeout` 中指定的时间时才会关闭。
#### NOTE
在 nginx 中,类似的指令称为 [keepalive_min_timeout](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_min_timeout)。
### listen
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `listen` address[:port] [`default_server`] [`ssl`] [http2 | `quic`] [`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 | `quic`] [`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 | `quic`] [`proxy_protocol`] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`accept_filter=`filter] [`deferred`] [`bind`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]]; |
|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 默认值 | `listen *:80` | `*:8000;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server |
设置监听套接字的 address 和 port，或服务器接受请求的 UNIX 域套接字的路径。address 也可以是主机名，例如：
```nginx
listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;
```
IPv6 地址用方括号指定：
```nginx
listen [::]:8000;
listen [::1];
```
UNIX 域套接字使用 `unix:` 前缀指定：
```nginx
listen unix:/var/run/angie.sock;
```
可以同时指定 address 和 port，或仅指定 address 或仅指定 port。
当省略某些部分时，适用以下规则：
- 如果仅给出 address，则使用端口 80。
- 如果仅给出 port，
Angie 将监听所有可用的 IPv4（以及 IPv6，如果已启用）接口。
该端口的第一个 `server` 块
将成为具有不匹配 `Host` 头的请求的默认服务器。
- 如果完全省略该指令，Angie 在以超级用户权限运行时使用 `*:80`，
否则使用 `*:8000`。
| `default_server` | 指定了此参数的服务器
将成为给定 address:port 对的默认服务器
（它们共同构成一个 *监听套接字*）。
如果没有带 `default_server` 参数的指令，
该监听套接字的默认服务器
将是配置中为该套接字提供服务的第一个服务器。 |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `ssl` | 表示在此监听套接字上接受的所有连接都应在 SSL 模式下工作。这允许为同时处理 HTTP 和 HTTPS 请求的服务器提供更 [紧凑的配置](https://cn.angie.software//angie/docs/configuration/ssl.md#compact-server)。 |
| `http2` | 配置端口接受 HTTP/2 连接。通常，为了使其工作，还应指定 `ssl` 参数，但 Angie 也可以配置为接受不带 SSL 的 HTTP/2 连接。
#### Deprecated
自 1.2.0 版本弃用.
请改用 [http2](https://cn.angie.software//angie/docs/configuration/modules/http/http_v2.md#http2) 指令。 |
| `quic` | 配置端口接受 QUIC 连接。
要使用此选项，
Angie 必须启用并配置 [HTTP3 模块](https://cn.angie.software//angie/docs/configuration/modules/http/http_v3.md#http-v3)。
设置 `quic` 后，
您还可以指定 `reuseport`
以便可以使用多个工作进程。 |
| `proxy_protocol` | 表示在此监听套接字上接受的所有连接都应使用 PROXY 协议。 |
`listen` 指令还可以指定几个特定于套接字相关系统调用的附加参数。这些参数可以在任何 `listen` 指令中指定，但对于给定的监听套接字只能指定一次：
| `setfib=`number | 为监听套接字设置路由表 FIB（`SO_SETFIB` 选项）。目前仅在 FreeBSD 上有效。 |
|--------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `fastopen=`number | 为监听套接字启用"TCP Fast Open"，并限制尚未完成三次握手的连接队列的最大长度。
#### WARNING
除非服务器能够处理多次接收带有数据的相同 SYN 数据包，否则不要启用"TCP Fast Open"。 |
| `backlog=`number | 设置 `listen()` 调用中的 `backlog` 参数，
该参数限制待处理连接队列的最大长度。默认情况下，
在 FreeBSD、DragonFly BSD 和 macOS 上 backlog 设置为 -1，
在其他平台上设置为 511。 |
| `rcvbuf=`size | 为监听套接字设置接收缓冲区大小（`SO_RCVBUF` 选项）。 |
| `sndbuf=`size | 为监听套接字设置发送缓冲区大小（`SO_SNDBUF` 选项）。 |
| `accept_filter=`filter | 为监听套接字设置接受过滤器的名称（`SO_ACCEPTFILTER` 选项），
该过滤器在将传入连接传递给 `accept()` 之前对其进行过滤。
这仅在 FreeBSD 和 NetBSD 5.0+ 上有效。
可能的值为 `dataready` 和 `httpready`。 |
| `deferred` | 指示在 Linux 上使用延迟 `accept()`
（`TCP_DEFER_ACCEPT` 套接字选项）。 |
| `bind` | 指示为给定的 address:port 对进行单独的 `bind()` 调用。
这很有用，因为如果有多个具有相同端口但不同地址的 `listen`
指令，并且其中一个 `listen` 指令监听给定 `port`
的所有地址（`*:port`），Angie 将只 `bind()` 到
`*:port`。应该注意的是，在这种情况下将进行 `getsockname()`
系统调用以确定接受连接的地址。如果使用了 `setfib`、`fastopen`、
`backlog`、`rcvbuf`、`sndbuf`、`accept_filter`、
`deferred`、`ipv6only`、`reuseport` 或 `so_keepalive`
参数，那么对于给定的 `address:port` 对将始终进行单独的 `bind()` 调用。 |
| `ipv6only=on` | `off` | 确定（通过 `IPV6_V6ONLY` 套接字选项）
监听通配符地址 [::] 的 IPv6 套接字是否只接受
IPv6 连接或同时接受 IPv6 和 IPv4 连接。此参数
默认开启。它只能在启动时设置一次。 |
| `reuseport` | 指示为每个工作进程创建单独的监听套接字
（在 Linux 3.9+ 和 DragonFly BSD 上使用 `SO_REUSEPORT` 套接字选项，
或在 FreeBSD 12+ 上使用 `SO_REUSEPORT_LB`），
允许内核在工作进程之间分配传入连接。目前仅在 Linux 3.9+、
DragonFly BSD 和 FreeBSD 12+ 上有效。
#### WARNING
不当使用 `reuseport` 参数
可能会带来安全隐患。 |
| `multipath` | 启用通过 [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP) 接受连接，
自 Linux 内核版本 5.6 起支持。
此参数与 `quic` **不兼容**。 |
| `so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`] | 为监听套接字配置"TCP keepalive"行为。
| `''` | 如果省略此参数，则套接字将使用操作系统的设置 |
|--------|--------------------------|
| `on` | 为套接字开启 `SO_KEEPALIVE` 选项 |
| `off` | 为套接字关闭 `SO_KEEPALIVE` 选项 | |
某些操作系统支持使用 `TCP_KEEPIDLE`、`TCP_KEEPINTVL` 和
`TCP_KEEPCNT` 套接字选项在每个套接字的基础上设置 TCP keepalive 参数。在这些系统上（目前包括 Linux、NetBSD、
Dragonfly、FreeBSD 和 macOS），可以使用
`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
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `location` ([ = | ~ | ~\* | ^~ ] uri | `@name`)+ { ... } |
|--------------------------------------------------------------------------------------|------------------------------------------------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
根据请求 URI 是否匹配任何匹配表达式来设置配置。
匹配是针对规范化的 URI 执行的，在解码以"%XX"形式编码的文本、解析对相对路径组件"."和".."的引用，以及可能将两个或多个相邻斜杠 [压缩](#merge-slashes) 为单个斜杠之后进行。
`location` 可以由前缀字符串定义，也可以由正则表达式定义。
正则表达式使用前置修饰符指定：
| `~*` | 不区分大小写的匹配 |
|--------|-------------|
| `~` | 区分大小写的匹配 |
为了找到与请求匹配的 location，Angie 首先检查使用前缀字符串定义的 location（前缀 location）。在这些 location 中，选择并记住具有最长匹配前缀的 location。
#### NOTE
对于不区分大小写的操作系统（如 macOS），前缀字符串匹配不区分大小写。
但是，匹配仅限于单字节区域设置。
然后按照正则表达式在配置文件中出现的顺序检查正则表达式。在第一次匹配后停止搜索，并使用相应的配置。如果没有找到与正则表达式的匹配，则使用之前记住的前缀 location 的配置。
除了下面提到的一些例外情况，`location` 块可以嵌套。
正则表达式可以创建捕获组，这些捕获组稍后可以与其他指令一起使用。
如果最长匹配前缀 location 具有 `^~` 修饰符，则不检查正则表达式。
此外，使用 `=` 修饰符，可以定义 URI 和 location 的精确匹配。如果找到精确匹配，则搜索终止。例如，如果 `/` 请求频繁发生，定义 `location =/` 将加快这些请求的处理速度，因为搜索在第一次比较后终止。这样的 location 不能包含嵌套的 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。
#### NOTE
如果前缀 `location` 以斜杠字符结尾且
[auto_redirect](#auto-redirect) 已启用,则会发生以下情况:
当请求到达时,其 URI 没有尾部斜杠
但在其他方面与前缀完全匹配,则会返回
代码为 301 的永久重定向,指向附加了斜杠的请求 URI。
对于精确 URI 匹配的 location,不会应用重定向:
```nginx
location /user/ {
proxy_pass http://user.example.com;
}
location =/user {
proxy_pass http://login.example.com;
}
```
`@` 前缀定义了一个 *命名* `location`。此类 location 不用于常规请求处理,
而是仅用于请求重定向。
它们不能嵌套,也不能包含嵌套 location。
#### 组合位置
多个定义相同配置块的 `location` 上下文可以通过在单个 `location` 中列出所有匹配表达式并使用单个配置块来压缩。这称为\*组合\* `location`。
假设前面示例中的配置 A、D 和 E 定义了相同的配置;您可以将它们组合成一个 `location`:
```nginx
location =/
^~/images/
~*\.(gif|jpg|jpeg)$ {
# 通用配置
}
```
命名的 `location` 也可以是组合的一部分:
```nginx
location =/
@named_combined {
#...
}
```
#### WARNING
组合 `location` 的匹配表达式修饰符和表达式本身之间不能有空格。
正确形式: `location ~*/match(ing|es|er)$ *...*`。
#### NOTE
目前,组合 `location` 不能\*\*直接\*\*包含设置了 URI 的 `proxy_pass` 指令,也不能包含 `api` 或 `alias`。
但是,这些指令可以在嵌套于组合位置内的位置中使用。
### log_not_found
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `log_not_found` `on` | `off`; |
|--------------------------------------------------------------------------------------|---------------------------------|
| 默认值 | `log_not_found on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用将未找到文件的错误记录到 [error_log](https://cn.angie.software//angie/docs/configuration/modules/core.md#error-log) 中。
### log_subrequest
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `log_subrequest` `on` | `off`; |
|--------------------------------------------------------------------------------------|----------------------------------|
| 默认值 | `log_subrequest off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用将子请求记录到 [access_log](https://cn.angie.software//angie/docs/configuration/modules/http/http_log.md#access-log) 中。
### max_headers
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `max_headers` number; |
|--------------------------------------------------------------------------------------|-------------------------|
| 默认值 | `max_headers 1000;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
设置允许的客户端请求头字段的最大数量。
如果超过此限制,将返回 `400 (Bad Request)` 错误。
当此指令在 [server](#server) 级别设置时,
可能会应用默认服务器的值。
有关更多信息,请参阅 [虚拟服务器选择](https://cn.angie.software//angie/docs/configuration/processing.md#virtual-server-selection) 部分。
### max_ranges
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `max_ranges` number; |
|--------------------------------------------------------------------------------------|------------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
限制字节范围请求中允许的最大范围数量。超过限制的请求将被视为未指定字节范围。默认情况下,范围数量不受限制。
| `0` | 完全禁用字节范围支持 |
|-------|--------------|
### merge_slashes
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `merge_slashes` `on` | `off`; |
|--------------------------------------------------------------------------------------|---------------------------------|
| 默认值 | `merge_slashes on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
启用或禁用将 URI 中两个或多个相邻斜杠压缩为单个斜杠。
请注意,压缩对于正确匹配前缀字符串和正则表达式位置至关重要。如果没有压缩,:samp://scripts/one.php 请求将不会匹配
```nginx
location /scripts/ { }
```
并且可能被作为静态文件处理。因此它会被转换为 `/scripts/one.php`。
如果 URI 包含 base64 编码的名称,则可能需要关闭压缩,因为 base64 在内部使用 "/" 字符。但是,出于安全考虑,最好避免关闭压缩。
如果在 [server](#server) 级别指定该指令,则可以使用默认服务器的值。
### msie_padding
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `msie_padding` `on` | `off`; |
|--------------------------------------------------------------------------------------|--------------------------------|
| 默认值 | `msie_padding on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用为状态大于 400 的 MSIE 客户端响应添加注释,以将响应大小增加到 512 字节。
### msie_refresh
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `msie_refresh` `on` | `off`; |
|--------------------------------------------------------------------------------------|--------------------------------|
| 默认值 | `msie_refresh off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用为 MSIE 客户端发出刷新而不是重定向。
### open_file_cache
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache` `off`;
`open_file_cache` `max=`N [`inactive=`time]; |
|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| 默认值 | `open_file_cache off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | 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
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_errors` `on` | `off`; |
|--------------------------------------------------------------------------------------|------------------------------------------|
| 默认值 | `open_file_cache_errors off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用通过 [open_file_cache](#open-file-cache) 缓存文件查找错误。
### open_file_cache_min_uses
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_min_uses` number; |
|--------------------------------------------------------------------------------------|--------------------------------------|
| 默认值 | `open_file_cache_min_uses 1;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置在 [open_file_cache](#open-file-cache) 指令的 `inactive` 参数配置的期间内,文件描述符在缓存中保持打开所需的最小文件访问次数。
### open_file_cache_valid
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `open_file_cache_valid` time; |
|--------------------------------------------------------------------------------------|---------------------------------|
| 默认值 | `open_file_cache_valid 60s;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置应验证 [open_file_cache](#open-file-cache) 元素的时间。
### output_buffers
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `output_buffers` number size; |
|--------------------------------------------------------------------------------------|---------------------------------|
| 默认值 | `output_buffers 2 32k;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置用于从磁盘读取响应的缓冲区数量和大小。
### port_in_redirect
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `port_in_redirect` `on` | `off`; |
|--------------------------------------------------------------------------------------|------------------------------------|
| 默认值 | `port_in_redirect on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用在 Angie 发出的 [绝对](#absolute-redirect) 重定向中指定端口。
在重定向中使用主服务器名称由 [server_name_in_redirect](#server-name-in-redirect) 指令控制。
### postpone_output
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `postpone_output` size; |
|--------------------------------------------------------------------------------------|---------------------------|
| 默认值 | `postpone_output 1460;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
如果可能,客户端数据的传输将被推迟,直到 Angie 至少有指定数量的字节要发送。
| `0` | 禁用推迟数据传输 |
|-------|------------|
### read_ahead
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `read_ahead` size; |
|--------------------------------------------------------------------------------------|------------------------|
| 默认值 | `read_ahead 0;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置在处理文件时内核的预读取量。
在 Linux 上,使用 `posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)` 系统调用,因此 size 参数会被忽略。
在 FreeBSD 上,使用 `fcntl(O_READAHEAD,` size ) 系统调用,该调用从 FreeBSD 9.0-CURRENT 开始支持。
### recursive_error_pages
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `recursive_error_pages` `on` | `off`; |
|--------------------------------------------------------------------------------------|-----------------------------------------|
| 默认值 | `recursive_error_pages off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用使用 [error_page](#error-page) 指令进行多次重定向。此类重定向的次数是 [有限的](#internal)。
### request_pool_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `request_pool_size` size; |
|--------------------------------------------------------------------------------------|-----------------------------|
| 默认值 | `request_pool_size 4k;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
允许精确调整每个请求的内存分配。此指令对性能的影响很小,通常不应使用。
### reset_timedout_connection
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `reset_timedout_connection` `on` | `off`; |
|--------------------------------------------------------------------------------------|---------------------------------------------|
| 默认值 | `reset_timedout_connection off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用重置超时连接和使用非标准代码 444 关闭的连接。重置按如下方式执行。在关闭套接字之前,为其设置 `SO_LINGER` 选项,超时值为 0。当套接字关闭时,TCP RST 被发送到客户端,并释放与此套接字关联的所有内存。这有助于避免长时间保持已关闭的套接字处于 FIN_WAIT1 状态且缓冲区已满。
#### NOTE
keep-alive 连接在超时时会正常关闭。
### resolver
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver` address ... [`valid=`time] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`zone]; |
|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, upstream |
配置用于将上游服务器名称解析为地址的名称服务器，例如：
```nginx
resolver 127.0.0.53 [::1]:5353;
```
地址可以指定为域名或 IP 地址，并可选端口。如果未指定端口，则使用端口 53。名称服务器以轮询方式查询。
#### NOTE
建议使用本地可信解析器，例如 `127.0.0.53` (systemd-resolved)，而非
公共解析器（如 `8.8.8.8`）。公共解析器会将 DNS 查询暴露给第三方，
并增加缓存投毒攻击的风险。
#### NOTE
该指令值会被嵌套块继承，
并可在其中根据需要覆盖。
在单个块内，该指令只能指定一次。
如果重复指定，则最后的定义生效。
默认情况下，Angie 使用响应的 TTL 值缓存答案。如果未指定 `resolver` 指令且不执行动态 DNS 查询（例如，在 [代理](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) 中使用固定名称而不使用变量时），则不需要指定解析器：名称将在启动时使用系统解析器进行解析。可选的 `valid` 参数允许覆盖此行为：
| `valid` | *可选* 参数允许覆盖响应缓存的有效期 |
|-----------|------------------------|
```nginx
resolver 127.0.0.53 [::1]:5353 valid=30s;
```
默认情况下，Angie 在解析时会同时查找 IPv4 和 IPv6 地址。
| `ipv4=off` | 禁用查找 IPv4 地址 |
|--------------|----------------|
| `ipv6=off` | 禁用查找 IPv6 地址 |
| `status_zone` | *可选* 参数;
启用在指定区域中收集 DNS 服务器请求和响应指标
([/status/resolvers/](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-resolvers)) |
|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### resolver_timeout
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver_timeout` time; |
|--------------------------------------------------------------------------------------|----------------------------------|
| 默认值 | `resolver_timeout 30s;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, upstream |
设置名称解析的超时时间,例如:
```nginx
resolver_timeout 5s;
```
### error_log_user_tag
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `error_log_user_tag` value; |
|--------------------------------------------------------------------------------------|--------------------------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, limit_except |
向错误日志记录添加特定于请求的标签。value 是一个 [复杂值](https://cn.angie.software//angie/docs/configuration/configfile.md#syntax),
可以使用变量。该指令可以多次指定以添加多个标签。
标签可以在 [error_log](https://cn.angie.software//angie/docs/configuration/modules/core.md#error-log) 中使用 `filter=tag:` 进行匹配。
### root
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `root` path; |
|--------------------------------------------------------------------------------------|----------------------------------------|
| 默认值 | `root html;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location |
设置请求的根目录。例如,使用以下配置
```nginx
location /i/ {
root /data/w3;
}
```
将发送 `/data/w3/i/top.gif` 文件来响应 `/i/top.gif` 请求。
path 值可以包含变量,但 [$document_root](#v-document-root) 和 [$realpath_root](#v-realpath-root) 除外。
文件路径的构造仅仅是将 URI 添加到 root 指令的值。如果需要修改 URI,应使用 [alias](#alias) 指令。
### satisfy
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `satisfy` `all` | `any`; |
|--------------------------------------------------------------------------------------|----------------------------|
| 默认值 | `satisfy all;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
如果所有 (`all`) 或至少一个 (`any`) [Access](https://cn.angie.software//angie/docs/configuration/modules/http/http_access.md#http-access)、[Auth Basic](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_basic.md#http-auth-basic) 或 [Auth Request](https://cn.angie.software//angie/docs/configuration/modules/http/http_auth_request.md#http-auth-request) 模块允许访问,则允许访问。
```nginx
location / {
satisfy any;
allow 192.168.1.0/32;
deny all;
auth_basic "closed site";
auth_basic_user_file conf/htpasswd;
}
```
### send_lowat
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `send_lowat` size; |
|--------------------------------------------------------------------------------------|------------------------|
| 默认值 | `send_lowat 0;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
如果该指令设置为非零值,Angie 将尝试通过使用 [kqueue](https://cn.angie.software//angie/docs/configuration/processing.md#kqueue) 方法的 `NOTE_LOWAT` 标志或 `SO_SNDLOWAT` 套接字选项来最小化客户端套接字上的发送操作次数。在这两种情况下都使用指定的大小。
### send_timeout
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `send_timeout` time; |
|--------------------------------------------------------------------------------------|------------------------|
| 默认值 | `send_timeout 60s;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置向客户端传输响应的超时时间。超时仅在两次连续的写操作之间设置,而不是用于整个响应的传输。如果客户端在此时间内没有收到任何内容,连接将被关闭。
### sendfile
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `sendfile` `on` | `off`; |
|--------------------------------------------------------------------------------------|----------------------------------------|
| 默认值 | `sendfile off;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location, if in location |
启用或禁用 `sendfile()` 的使用。
[aio](#aio) 可用于为 `sendfile()` 预加载数据:
```nginx
location /video/ {
sendfile on;
tcp_nopush on;
aio on;
}
```
在此配置中,:samp:sendfile() 使用 `SF_NODISKIO` 标志调用,这使其不会在磁盘 I/O 上阻塞,而是报告数据不在内存中。然后 Angie 通过读取一个字节来启动异步数据加载。在第一次读取时,FreeBSD 内核将文件的前 128K 字节加载到内存中,但后续读取将仅以 16K 块加载数据。这可以使用 [read_ahead](#read-ahead) 指令更改。
### sendfile_max_chunk
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `sendfile_max_chunk` size; |
|--------------------------------------------------------------------------------------|------------------------------|
| 默认值 | `sendfile_max_chunk 2m;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
限制单次 `sendfile()` 调用中可以传输的数据量。如果没有限制,一个快速连接可能会完全占用工作进程。
### server
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server` { ... } |
|--------------------------------------------------------------------------------------|--------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
设置虚拟服务器的配置。基于 IP(基于 IP 地址)和基于名称(基于 "Host" 请求头字段)的虚拟服务器之间没有明确的分隔。相反,:ref:listen 指令描述应该接受服务器连接的所有地址和端口,:ref:server_name 指令列出所有服务器名称。
[Angie 如何处理请求](https://cn.angie.software//angie/docs/configuration/processing.md#request-processing) 文档中提供了配置示例。
### server_name
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name` name ...; |
|--------------------------------------------------------------------------------------|---------------------------|
| 默认值 | `server_name ""`; |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | 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\d+\.example\.com$ www.example.com;
}
```
正则表达式可以包含捕获,这些捕获可以在其他指令中使用:
```nginx
server {
server_name ~^(www\.)?(.+)$;
location / {
root /sites/$2;
}
}
server {
server_name _;
location / {
root /sites/default;
}
}
```
正则表达式中的命名捕获会创建变量,这些变量可以在其他指令中使用:
```nginx
server {
server_name ~^(www\.)?(?.+)$;
location / {
root /sites/$domain;
}
}
server {
server_name _;
location / {
root /sites/default;
}
}
```
#### NOTE
如果指令的参数设置为 [$hostname](#v-hostname),
则使用机器名称。
也可以指定空服务器名称:
```nginx
server {
server_name www.example.com "";
}
```
按名称搜索虚拟服务器时,
如果名称匹配多个指定的变体
(例如,通配符名称和正则表达式都匹配),
将按以下优先级顺序选择第一个匹配的变体:
- 精确名称;
- 以星号开头的最长通配符名称,例如 `*.example.com`;
- 以星号结尾的最长通配符名称,例如 `mail.*`;
- 第一个匹配的正则表达式(按配置文件中出现的顺序),
包括空名称。
#### WARNING
要在 TLS 中使用 `server_name`,
需要 TLS 连接终止。
此指令匹配 HTTP 请求中的 `Host`,
因此必须完成握手并解密连接。
### server_name_in_redirect
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name_in_redirect` `on` | `off`; |
|--------------------------------------------------------------------------------------|-------------------------------------------|
| 默认值 | `server_name_in_redirect off`; |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用在 Angie 发出的 [绝对](#absolute-redirect) 重定向中使用由 [server_name](#server-name) 指令指定的主服务器名称。
| `on` | 使用由 [server_name](#server-name) 指令设置的主服务器名称 |
|--------|-----------------------------------------------|
| `off` | 使用 "Host" 请求头字段中的名称。如果此字段不存在,则使用服务器的 IP 地址。 |
重定向中端口的使用由 [port_in_redirect](#port-in-redirect) 指令控制。
### server_names_hash_bucket_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_names_hash_bucket_size` size; |
|--------------------------------------------------------------------------------------|----------------------------------------------------|
| 默认值 | `server_names_hash_bucket_size 32` | `64` | `128;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
设置服务器名称哈希表的桶大小。默认值取决于处理器缓存行的大小。有关设置哈希表的详细信息在 [单独的文档](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes) 中提供。
### server_names_hash_max_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_names_hash_max_size` size; |
|--------------------------------------------------------------------------------------|--------------------------------------|
| 默认值 | `server_names_hash_max_size 512`; |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
设置服务器名称哈希表的最大大小。有关设置哈希表的详细信息在 [单独的文档](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes) 中提供。
### server_tokens
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_tokens` `on` | `off` | `build` | string; |
|--------------------------------------------------------------------------------------|----------------------------------------------------|
| 默认值 | `server_tokens on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用在错误页面和 `Server` 响应头字段中显示 Angie 版本。
`build` 参数启用显示构建名称,
该名称由相应的 [configure](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 参数设置,
与版本一起显示。
在 Angie PRO 中,如果指令设置了一个 string,该字符串也可以包含变量,
错误页面和 `Server` 响应头字段
将使用该字符串的变量插值后的值
来代替服务器名称、版本和构建名称。
空 string 将禁用 `Server` 字段的显示。
### status_zone
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `status_zone` `off` | zone | key `zone=`zone[:number]; |
|--------------------------------------------------------------------------------------|----------------------------------------------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server, location, if in location |
分配一个共享内存区域用于收集
[/status/http/location_zones/](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-location-zones) 和 [/status/http/server_zones/](https://cn.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-server-zones) 指标。
多个 `server` 上下文
可以共享同一个区域进行数据收集;
特殊值 `off`
在嵌套的 `location` 块中禁用数据收集。
使用单个 zone 值的语法
将当前上下文的所有指标合并到一个共享内存区域中:
```nginx
server {
listen 80;
server_name *.example.com;
status_zone single;
# ...
}
```
替代语法允许设置以下参数:
| key | 包含变量的字符串,其值决定区域中请求的分组。
所有在替换后产生相同值的请求
被分组在一起。如果替换产生空值,
则不更新指标。 |
|-------------|------------------------------------------------------------------------------|
| zone | 共享内存区域的名称。 |
| number (可选) | 用于收集指标的独立组的最大数量。
如果新的 key 值超过此限制,它们将被分组到 `zone` 下。
默认值为 1。 |
在以下示例中,
所有共享相同 `$host` 值的请求
被分组到 `host_zone` 中。
为每个唯一的 `$host` 单独跟踪指标,
直到有 10 个指标组。
一旦达到此限制,
任何额外的 `$host` 值都将包含在 `host_zone` 下:
```nginx
server {
listen 80;
server_name *.example.com;
status_zone $host zone=host_zone:10;
location / {
proxy_pass http://example.com;
}
}
```
因此,生成的指标在 API 输出中按各个主机分割。
### subrequest_output_buffer_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `subrequest_output_buffer_size` size; |
|--------------------------------------------------------------------------------------|--------------------------------------------|
| 默认值 | `subrequest_output_buffer_size 4k` | `8k;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置用于存储子请求响应体的缓冲区大小。
默认情况下,缓冲区大小等于一个内存页。这是
`4K` 或 `8K`,取决于平台。它可以设置得更小。
#### NOTE
该指令仅适用于响应体保存在内存中的子请求。例如,这样的子请求由 [SSI](https://cn.angie.software//angie/docs/configuration/modules/http/http_ssi.md#ssi-include-set) 创建。
### tcp_nodelay
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `tcp_nodelay` `on` | `off`; |
|--------------------------------------------------------------------------------------|-------------------------------|
| 默认值 | `tcp_nodelay on;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用 `TCP_NODELAY` 选项的使用。当连接转换到保持活动状态时启用该选项。此外,它在 SSL 连接、无缓冲代理和 [WebSocket 代理](https://cn.angie.software//angie/docs/configuration/processing.md#websocket-proxy) 中也被启用。
### tcp_nopush
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `tcp_nopush` `on` | `off`; |
|--------------------------------------------------------------------------------------|------------------------------|
| 默认值 | `tcp_nopush off`; |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
启用或禁用在 FreeBSD 上使用 `TCP_NOPUSH` 套接字选项或在 Linux 上使用 `TCP_CORK` 套接字选项。这些选项仅在使用 [sendfile](#sendfile) 时启用。启用该选项允许
* 在 Linux 和 FreeBSD 4.\* 上,在一个数据包中发送响应头和文件的开头;
* 以完整数据包发送文件。
### try_files
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `try_files` file ... uri;
`try_files` file ... =code; |
|--------------------------------------------------------------------------------------|------------------------------------------------------------------|
| 默认值 | — |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | server, location |
按指定顺序检查文件是否存在,并使用第一个找到的文件进行请求处理;处理在当前 location 的上下文中执行。文件的路径根据 file 参数按照 [root](#root) 和 [alias](#alias) 指令构造。可以通过在名称末尾指定斜杠来检查目录是否存在,例如 `$uri/`。如果没有找到任何文件,则进行内部重定向到最后一个参数中指定的 uri。
例如:
```nginx
location /images/ {
try_files $uri /images/default.gif;
}
location = /images/default.gif {
expires 30s;
}
```
最后一个参数可以是用于内部重定向的 URI、
对命名 location 的引用(例如 `@drupal`)、
或以 `=code` 形式的响应码(例如 `=404`):
```nginx
location / {
try_files $uri $uri/index.html $uri.html =404;
}
```
应该注意的是,过度使用 `try_files` 指令
会增加系统调用的数量,
这可能会对性能产生负面影响。
因此,:samp:try_files 不应该用于复制
实际上是默认行为的行为,例如:
```nginx
location /bad_pattern {
# try_files $uri $uri/ =404; # 不推荐!
}
```
此外,:samp:try_files 不应该
仅用于在文件不存在时进行重定向。
原因是 `try_files` 指令有两个特点:
- 首先,它检查每个文件是否存在,
这会增加系统负载。
- 其次,任何文件打开错误(例如 `打开文件过多`、
权限错误)也被视为文件不存在并触发回退
到备用处理程序,这可能会用成功响应掩盖 5xx 错误
并导致错误的缓存。
因此,在实践中,可能会遇到以下有问题的结构:
```nginx
location / {
try_files $uri $uri/ @drupal; # 不推荐!
}
```
这里的问题是唯一的目的是重定向。
使用 `try_files` 会导致上述缺点,
但没有任何好处,
因为不需要检查文件是否存在。
正确的解决方案是使用 [error_page](#error-page) 指令,
它没有这些缺点:
```nginx
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;
# ...
}
```
`try_files` 指令在将请求传递给同一块中配置的 FastCGI 服务器之前
检查 PHP 文件是否存在;
这里使用 `try_files` 是合理的。
### 代理到 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 / {
error_page 404 = @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;
# ... 其他 fastcgi_param
}
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;
# ... 其他 fastcgi_param
}
```
### 与 Wordpress 和 Joomla 一起使用的示例:
```nginx
location / {
error_page 404 = @wordpress;
}
location ~ \.php$ {
try_files $uri @wordpress;
fastcgi_pass ...;
fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
# ... 其他 fastcgi_param
}
location @wordpress {
fastcgi_pass ...;
fastcgi_param SCRIPT_FILENAME /path/to/index.php;
# ... 其他 fastcgi_param
}
```
### types
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `types` { ... } |
|--------------------------------------------------------------------------------------|------------------------------------------------------------|
| 默认值 | `types *text/html html; image/gif gif; image/jpeg jpg;* ` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
将文件扩展名映射到响应的 MIME 类型。扩展名不区分大小写。多个扩展名可以映射到一个类型,例如:
```nginx
types {
application/octet-stream bin exe dll;
application/octet-stream deb;
application/octet-stream dmg;
}
```
Angie 随附了一个足够完整的映射表,位于 `conf/mime.types` 文件中。
要使特定的 location 对所有响应返回 "application/octet-stream" MIME 类型,可以使用以下配置:
```nginx
location /download/ {
types { }
default_type application/octet-stream;
}
```
### types_hash_bucket_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `types_hash_bucket_size` size; |
|--------------------------------------------------------------------------------------|----------------------------------|
| 默认值 | `types_hash_bucket_size 64;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置类型哈希表的桶大小。有关设置哈希表的详细信息,请参阅 [单独讨论](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。
### types_hash_max_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `types_hash_max_size` size; |
|--------------------------------------------------------------------------------------|-------------------------------|
| 默认值 | `types_hash_max_size 1024;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server, location |
设置类型哈希表的最大大小。有关设置哈希表的详细信息,请参阅 [单独讨论](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。
### underscores_in_headers
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `underscores_in_headers` `on` | `off`; |
|--------------------------------------------------------------------------------------|------------------------------------------|
| 默认值 | `underscores_in_headers off`; |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http, server |
启用或禁用在客户端请求头字段中使用下划线。当禁用下划线的使用时,名称包含下划线的请求头字段将被标记为无效,并受 [ignore_invalid_headers](#ignore-invalid-headers) 指令的约束。
如果该指令在 [server](#server) 级别指定,则可以使用默认服务器的值。
### variables_hash_bucket_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `variables_hash_bucket_size` size; |
|--------------------------------------------------------------------------------------|--------------------------------------|
| 默认值 | `variables_hash_bucket_size 64;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
设置变量哈希表的桶大小。有关设置哈希表的详细信息,请参阅 [单独讨论](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。
### variables_hash_max_size
| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `variables_hash_max_size` size; |
|--------------------------------------------------------------------------------------|-----------------------------------|
| 默认值 | `variables_hash_max_size 2048;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | http |
设置变量哈希表的最大大小。有关设置哈希表的详细信息,请参阅 [单独讨论](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。
## 内置变量
`http_core` 模块支持与 Apache Server 变量名称匹配的内置变量。首先,这些是表示客户端请求头字段的变量,例如 `$http_user_agent`、`$http_cookie` 等。此外,还有其他变量:
### `$angie_version`
Angie 版本
### `$arg_`
请求行中的参数 name
### `$args`
请求行中的参数
### `$binary_remote_addr`
二进制形式的客户端地址,对于 IPv4 地址,值的长度始终为 4 字节,对于 IPv6 地址则为 16 字节
### `$body_bytes_sent`
发送给客户端的字节数,不包括响应头;此变量与 `mod_log_config` Apache 模块的 "%B" 参数兼容
### `$bytes_sent`
发送给客户端的字节数
### `$connection`
连接序列号
### `$connection_requests`
通过一个连接发出的当前请求数
### `$connection_time`
连接时间(以秒为单位),具有毫秒分辨率
### `$content_length`
`Content-Length` 请求头字段
### `$content_type`
`Content-Type` 请求头字段
### `$cookie_`
具有指定 name 的 cookie
### `$document_root`
当前请求的 [root](#root) 或 [alias](#alias) 指令的值
### `$document_uri`
与 [$uri](#v-uri) 相同
### `$host`
按以下优先顺序:请求行中的主机名,或 "Host" 请求头字段中的主机名,或与请求匹配的服务器名称
### `$hostname`
主机名
### `$http_`
任意请求头字段;变量名的最后部分对应于转换为小写并将破折号替换为下划线的字段名称
### `$https`
如果连接在 SSL 模式下运行,则为 `on`,否则为空字符串
### `$is_args`
如果请求行有参数,则为 `?`,否则为空字符串
### `$is_request_port`
如果 [$request_port](#v-request-port) 值非空,则为 `:`,否则为空字符串
### `$limit_rate`
设置此变量可启用响应速率限制;参见 [limit_rate](#limit-rate)
### `$msec`
当前时间(以秒为单位),具有毫秒分辨率
### `$nginx_version`
nginx 版本
### `$pid`
工作进程的 PID
### `$pipe`
如果请求是流水线式的,则为 `p`,否则为 `.`
### `$proxy_protocol_addr`
来自 PROXY 协议头的客户端地址
必须先通过在 [listen](#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。
### `$proxy_protocol_port`
来自 PROXY 协议头的客户端端口
必须先通过在 [listen](#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。
### `$proxy_protocol_server_addr`
来自 PROXY 协议头的服务器地址
必须先通过在 [listen](#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。
### `$proxy_protocol_server_port`
来自 PROXY 协议头的服务器端口
必须先通过在 [listen](#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。
### `$proxy_protocol_tlv_`
来自 PROXY 协议头的 TLV。name 可以是 TLV 类型名称或其数值。在后一种情况下,该值为十六进制,应以 `0x` 为前缀:
```none
$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01
```
SSL TLV 也可以通过 TLV 类型名称或其数值访问,两者都以 `ssl_` 为前缀:
```none
$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](#listen) 指令中设置 `proxy_protocol` 参数来启用 PROXY 协议。
### `$query_string`
与 [$args](#v-args) 相同
### `$realpath_root`
与当前请求的 [root](#root) 或 [alias](#alias) 指令的值对应的绝对路径名,所有符号链接都解析为实际路径
### `$remote_addr`
客户端地址
### `$remote_port`
客户端端口
### `$remote_user`
通过基本身份验证提供的用户名
### `$request`
完整的原始请求行
### `$request_body`
请求体
当请求体被读取到 [内存缓冲区](#client-body-buffer-size) 时,该变量的值在由 [proxy_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass)、[fastcgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass)、[uwsgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass) 和 [scgi_pass](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass) 指令处理的位置中\*可用\*。
### `$request_body_file`
包含请求体的临时文件名
在处理结束时,需要删除该文件。要始终将请求体写入文件,请启用 [client_body_in_file_only](#client-body-in-file-only)。在代理请求或向 FastCGI/uwsgi/SCGI 服务器发送请求时传递临时文件名时,应分别使用 [proxy_pass_request_body off](https://cn.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass-request-body)、[fastcgi_pass_request_body off](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass-request-body)、[uwsgi_pass_request_body off](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass-request-body) 或 [scgi_pass_request_body off](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass-request-body) 指令禁用请求体本身的传递。
### `$request_completion`
如果请求已完成,则为 `OK`,否则为空字符串
### `$request_filename`
当前请求的文件路径,基于 [root](#root) 或 [alias](#alias) 指令以及请求 URI
### `$request_id`
从 16 个随机字节生成的唯一请求标识符,以十六进制表示
### `$request_length`
请求长度(包括请求行、头和请求体)
### `$request_method`
请求方法,通常为 `GET` 或 `POST`
### `$request_port`
按以下优先顺序:请求 URI 的 authority 组件中的端口号,或 "Host" 请求头字段中的端口号
### `$request_time`
请求处理时间(以秒为单位),具有毫秒分辨率;从客户端读取第一个字节以来经过的时间
### `$request_uri`
完整的原始请求 URI（带参数），在请求处理过程中不会被修改；参阅 [$uri](#v-uri) 了解当前（可能已重写的）URI
### `$scheme`
请求方案,"http" 或 "https"
### `$sent_body`
子请求或外部请求的响应体(当其存储在内存中时);否则为空字符串
### `$sent_http_`
任意响应头字段;变量名的最后部分对应于转换为小写并将破折号替换为下划线的字段名称
### `$sent_trailer_`
在响应末尾发送的任意字段;变量名的最后部分对应于转换为小写并将破折号替换为下划线的字段名称
### `$server_addr`
接受请求的服务器地址
计算此变量的值通常需要一次系统调用。为避免系统调用,:ref:listen 指令必须指定地址并使用 `bind` 参数。
### `$server_name`
接受请求的服务器名称
### `$server_port`
接受请求的服务器端口
### `$server_protocol`
请求协议,通常为 "HTTP/1.0"、"HTTP/1.1" 或 "HTTP/2.0"
### `$status`
响应状态
### `$time_iso8601`
ISO 8601 标准格式的本地时间
### `$time_local`
通用日志格式的本地时间
### `$tcpinfo_rtt, $tcpinfo_rttvar, $tcpinfo_snd_cwnd, $tcpinfo_rcv_space`
关于客户端 TCP 连接的信息;在支持 `TCP_INFO` 套接字选项的系统上可用
### `$uri`
请求中的当前 URI,已 [规范化](#location)
`$uri` 的值可能在请求处理过程中发生变化,例如在使用 [rewrite](https://cn.angie.software//angie/docs/configuration/modules/http/http_rewrite.md#id5) 进行重写时、执行内部重定向时,或在使用索引文件时。