更多nginx模块指令

ngx_http_rewrite_module 模块是 Nginx 中一个非常强大和灵活的模块，主要用于修改请求 URI、执行重定向以及根据条件选择不同的配置。它依赖于 PCRE (Perl Compatible Regular Expressions) 正则表达式来实现这些功能。

指令处理顺序

理解 rewrite 模块指令的处理顺序至关重要，因为它决定了你的配置如何生效。这些指令（break, if, return, rewrite, set）的执行顺序如下：

1. 服务器级别 (server level) 的指令会按顺序依次执行。
2. 重复执行以下步骤（循环）：
   • 根据当前的请求 URI 搜索匹配的 location 块。
   • 执行在找到的 location 块内部定义的 rewrite 模块指令，它们也会按顺序依次执行。
   • 如果请求 URI 在此过程中被 rewrite 指令修改了，那么这个循环会重新开始，Nginx 会再次根据新的 URI 搜索 location。这个循环最多重复 10 次，以防止无限循环。如果超过 10 次，Nginx 会返回 500 错误。

指令详解

break

• 语法：break;
• 默认值：无
• 上下文：server, location, if

break 指令的作用是停止当前这一层级 ngx_http_rewrite_module 指令的进一步处理。

• 如果 break 在 location 块内部使用，那么请求会继续在该 location 块内处理，但不会再执行当前 location 块内剩余的 rewrite 模块指令。
• break 不会像 rewrite ... last 那样导致 Nginx 重新搜索 location。

示例：

if ($slow) {
    limit_rate 10k; # 限制速度为 10kbps
    break;         # 停止当前 if 块内的 rewrite 模块指令处理
}

如果 $slow 为真，limit_rate 10k; 生效，然后 break 停止 if 块内 rewrite 模块指令的处理（尽管这里没有其他 rewrite 模块指令，但它防止了后续可能存在的指令执行）。

if (condition) { ... }

• 语法：if (condition) { ... }
• 默认值：无
• 上下文：server, location

if 指令会评估一个条件。如果条件为真，则执行大括号 {...} 内的 rewrite 模块指令，并且请求会应用 if 指令内部的配置。if 块内部的配置会继承自上一个配置层级。

条件 (condition) 可以是以下几种：

• 变量名：
  • 如果变量的值是空字符串或 "0"，则条件为假 (false)。
  • 在 1.0.1 版本之前，任何以 "0" 开头的字符串都被认为是假。
• 变量与字符串比较：使用 = (等于) 和 != (不等于) 运算符。
• 变量与正则表达式匹配：
  • ~：区分大小写的匹配。
  • ~*：不区分大小写的匹配。
  • !~：不区分大小写的非匹配。
  • !~*：区分大小写的非匹配。
  • 正则表达式中可以包含捕获组，这些捕获组可以通过 $1..$9 变量在后续指令中重复使用。
  • 如果正则表达式包含 } 或 ; 字符，整个表达式需要用单引号或双引号括起来。
• 文件/目录/符号链接存在性检查：
  • -f 和 !-f：检查文件是否存在。
  • -d 和 !-d：检查目录是否存在。
  • -e 和 !-e：检查文件、目录或符号链接是否存在。
  • -x 和 !-x：检查文件是否可执行。

示例：

if ($http_user_agent ~ MSIE) { # 如果用户代理包含 MSIE (区分大小写)
    rewrite ^(.*)$ /msie/$1 break; # 重写 URI，并停止处理
}

if ($http_cookie ~* "id=([^;]+)(?:;|$)") { # 如果 cookie 中有 id
    set $id $1; # 将 id 的值赋给变量 $id
}

if ($request_method = POST) { # 如果请求方法是 POST
    return 405; # 返回 405 Method Not Allowed
}

if ($invalid_referer) { # 如果 referer 无效 (由 valid_referers 指令设置)
    return 403; # 返回 403 Forbidden
}

return

• 语法：
  • return code [text];
  • return code URL;
  • return URL;
• 默认值：无
• 上下文：server, location, if

return 指令会停止处理当前请求并向客户端返回指定的响应代码。

• code：HTTP 状态码。
  • 非标准代码 444 会直接关闭连接，不发送任何响应头。
  • 从 0.8.42 版本开始，对于 301 (永久重定向), 302 (临时重定向), 303 (See Other), 307 (Temporary Redirect), 308 (Permanent Redirect) 这些重定向代码，可以指定一个 URL。
  • 对于其他代码，可以指定响应体 文本 (text)。
  • 响应体文本和重定向 URL 都可以包含变量。
  • 作为特殊情况，如果重定向 URL 是服务器本地的 URI，Nginx 会根据请求的 scheme ($scheme)、server_name_in_redirect 和 port_in_redirect 指令自动构成完整的重定向 URL。
• URL：作为唯一参数时，表示使用 302 (临时重定向) 返回指定的 URL。该 URL 必须以 "http://"、"https://" 或 "$scheme" 开头。URL 中可以包含变量。

注意：在 Nginx 0.7.51 版本之前，可返回的代码非常有限。307 和 308 状态码在早期版本中不被视为重定向。

rewrite

• 语法：rewrite regex replacement [flag];
• 默认值：无
• 上下文：server, location, if

如果请求 URI 匹配指定的正则表达式 (regex)，则将 URI 修改为 replacement 字符串。rewrite 指令会按照它们在配置文件中出现的顺序依次执行。可以使用可选的标志 (flag) 参数来终止进一步的指令处理。

• 如果 replacement 字符串以 "http://"、"https://" 或 "$scheme" 开头，处理会立即停止，并向客户端返回一个重定向响应。

可选的标志 (flag) 参数：

• last：
  • 停止处理当前这一组 ngx_http_rewrite_module 指令。
  • 重新开始搜索与修改后的 URI 匹配的 location 块。这是一个内部重定向，Nginx 会再次执行 location 查找过程。
• break：
  • 停止处理当前这一组 ngx_http_rewrite_module 指令。
  • 请求会继续在当前 location 块内处理，不会重新搜索 location。
• redirect：
  • 返回一个带 302 代码的临时重定向。
  • 当 replacement 字符串不以 "http://"、"https://" 或 "$scheme" 开头时使用。
• permanent：
  • 返回一个带 301 代码的永久重定向。

完整的重定向 URL 会根据请求 scheme ($scheme)、server_name_in_redirect 和 port_in_redirect 指令来构成。

示例：

server {
    ...
    # 如果请求 URI 是 /download/xxx/media/yyy.ext，则重写为 /download/xxx/mp3/yyy.mp3
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
    # 如果请求 URI 是 /download/xxx/audio/yyy.ext，则重写为 /download/xxx/mp3/yyy.ra
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  last;
    return  403; # 如果前面的 rewrite 都没有匹配，则返回 403
    ...
}

在这个 server 级别的例子中，使用了 last 标志。这意味着如果 URI 被重写，Nginx 会重新进行 location 查找。

重要提示：如果将这些 rewrite 指令放在一个 location 块内部，last 标志应该替换为 break，否则 Nginx 可能会进入最多 10 次的循环，并最终返回 500 错误。

location /download/ {
    # 在 location 内部使用 break，因为如果 URI 被修改，我们不希望重新搜索 location
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  break;
    return  403;
}

• 参数处理：如果 replacement字符串中包含新的请求参数，那么之前的请求参数会自动附加在它们之后。如果你不希望附加这些参数，可以在 replacement字符串的末尾加上一个问号 ?，例如：

  nginx复制

  rewrite ^/users/(.*)$ /show?user=$1? last; # 末尾的 ? 阻止附加原有参数

• 如果正则表达式包含 } 或 ; 字符，整个表达式需要用单引号或双引号括起来。

rewrite_log

• 语法：rewrite_log on | off;
• 默认值：rewrite_log off;
• 上下文：http, server, location, if

启用或禁用 ngx_http_rewrite_module 模块指令处理结果的日志记录。日志会输出到 error_log 中，级别为 notice。这对于调试 rewrite 规则非常有用。

set

• 语法：set $variable value;
• 默认值：无
• 上下文：server, location, if

为指定的 $variable 设置一个 value。value 可以包含文本、其他变量或它们的组合。

uninitialized_variable_warn

• 语法：uninitialized_variable_warn on | off;
• 默认值：uninitialized_variable_warn on;
• 上下文：http, server, location, if

控制是否记录关于未初始化变量的警告。

ngx_http_rewrite_module 是 Nginx 配置中非常核心和强大的部分，它允许你灵活地控制请求的流向和 URI 的重写。理解 break 和 last 标志的区别，以及内部重定向的工作原理，是正确使用该模块的关键。

ngx_http_core_module

指令

absolute_redirect

| Syntax: | on | off; | | :------- | ---------------------------- | | Default: | absolute_redirect on; | | Context: | http, server, location |

该指令出现在 1.11.8 版本中。

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

alias

另请参阅server_name_in_redirect 和port_in_redirect指令。

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

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

当请求/i/top.gif时，文件/data/w3/images/top.gif将被发送。

path的值可以包含除$document_root和$realpath_root之外的变量。

如果在正则表达式定义的位置中使用alias，则该正则表达式应包含捕获，而alias应引用这些捕获（0.7.40），例如：

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

当location匹配alias指令值的最后一部分时：

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

最好使用root指令替代：

复制

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

default_type

定义响应的默认MIME类型。可以用types指令设置文件名扩展到MIME类型的映射。

error_page

定义指定错误时显示的URI。一个uri值可以包含变量。

例子:

复制

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

这会导致内部重定向到指定的uri，客户端请求方法更改为“GET”（对于除“GET”和“HEAD”之外的所有方法）。

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

error_page 404 =200 /empty.gif;

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

error_page 404 = /404.php;

如果在内部重定向期间不需要更改URI和方法，则可以将错误处理传递到指定位置：

location / {
    error_page 404 = @fallback;
}

location @fallback {
    proxy_pass http://backend;
}

如果uri处理导致错误，则将上次发生错误的状态码返回给客户端。

也可以使用URL重定向进行错误处理：

复制

error_page 403      http://example.com/forbidden.html;
error_page 404 =301 http://example.com/notfound.html;

在这种情况下，默认情况下，返回给客户端的响应码是302。它只能更改为重定向状态码中的一种（301、302、303、307和308）。

当且仅当当前级别上没有定义error_page指令时，这些指令从上一个配置级别继承。

http

提供指定HTTP服务器指令的配置文件上下文。

internal

指定指定的位置只能用于内部请求。对于外部请求，返回客户端错误404 （Not Found）。内部请求如下：

• 请求通过error_page、index、internal_redirect、random_index和try_files指令重定向；

• 通过“X-Accel-Redirect”响应头字段重定向来自上游服务器的请求；

• 由ngx_http_ssi_module模块的“include virtual”命令、ngx_http_addition_module模块指令、auth_request和mirror指令形成的子请求

• 由rewrite指令更改的请求。

error_page 404 /404.html;

location = /404.html {
    internal;
}

每个请求最多只能有10个内部重定向，以防止在不正确的配置中发生请求处理周期。如果达到此限制，则返回500错误（服务器内部错误）。在这种情况下，“重写或内部重定向循环”消息可以在错误日志中看到。

limit_except

限制一个location内允许的HTTP方法。method参数可以是以下之一：GET、HEAD、POST、PUT、DELETE、MKCOL、COPY、MOVE、OPTIONS、PROPFIND、propatch、LOCK、UNLOCK或PATCH。允许使用GET方法使得HEAD方法也可以使用。访问其他方法可以被限制使用ngx_http_access_module, ngx_http_auth_basic_module，和ngx_http_auth_jwt_module（1.13.10）模块指令：

复制

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

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

listen

| Syntax: | **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*]]; | | :------- | ------------------------------------------------------------ | | Default: | listen *:80 | *:8000; | | Context: | server |

为IP设置address和port，为unix域套接字设置path，服务器将在其上接受请求。address和port都可以指定，或者只能指定address和port。address也可以是主机名，例如：

复制

listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;

IPv6 addresses (0.7.36) are specified in square brackets:

复制

listen [::]:8000;
listen [::1];

UNIX-domain sockets (0.8.21) are specified with the “unix:” prefix:

复制

listen unix:/var/run/nginx.sock;

如果只给出address，则使用端口80。

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

default_server参数，如果存在，将导致服务器成为指定的address:port对的默认服务器。如果所有指令都没有default_server参数，那么第一个具有address:port的服务器将是这对指令的默认服务器。

参数ssl允许指定该端口上接受的所有连接都工作在ssl模式。这为同时处理HTTP和HTTPS请求的服务器提供了更紧凑的配置。

http2参数配置端口接受HTTP/2连接。通常情况下，ssl参数也应该指定，但nginx也可以配置为接受不带ssl的HTTP/2连接。

该参数已被弃用，应该使用http2指令代替。

location

| Syntax: | **location** [ = | ~ | ~* | ^~ ] *uri* { ... } **location** @*name* { ... } | | :------- | ------------------------------------------------------------ | | Default: | — | | Context: | server, location |

根据请求URI设置配置。

在解码以%XX形式编码的文本后，解析对相对路径分量的引用后，对规范化的URI执行匹配。.和..，以及可能的compression两个或多个相邻的斜杠成一个斜杠。

位置可以通过前缀字符串定义，也可以通过正则表达式定义。正则表达式使用前面的“~*”修饰符（用于大小写不敏感的匹配），或“~”修饰符（用于大小写敏感的匹配）。为了找到与给定请求匹配的位置，nginx首先检查使用前缀字符串定义的位置（前缀位置）。其中，选择匹配前缀最长的位置并记忆。然后检查正则表达式，按照它们在配置文件中出现的顺序。正则表达式的搜索在第一次匹配时结束，然后使用相应的配置。如果没有找到正则表达式的匹配，则使用前面记住的前缀位置的配置。

location块可以嵌套，下面会提到一些例外情况。

此外，使用“=”修饰符可以定义精确匹配的URI和位置。如果找到精确匹配，则终止搜索。例如，如果一个“/”请求频繁发生，定义“location = /”将加速这些请求的处理，因为搜索在第一次比较后立即结束。这样的位置显然不能包含嵌套位置。

让我们用一个例子来说明上面的内容：

复制

location = / {
    [ configuration A ]
}

location / {
    [ configuration B ]
}

location /documents/ {
    [ configuration C ]
}

location ^~ /images/ {
    [ configuration D ]
}

location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

“/”请求将匹配配置A，“/index.html”请求将匹配配置B，“/documents/document.html”请求将匹配配置C，“/images/1.gif”请求将匹配配置D，“‘ /documents/1.jpg ’”请求将匹配配置E。

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

Nginx 自动重定向行为

当你的 Nginx 配置中，一个 location 块是由一个以斜杠 / 结尾的前缀字符串定义的，并且这个 location 块内部使用了 proxy_pass、fastcgi_pass 等反向代理或上游传递指令时，Nginx 会执行一个特殊的处理。

具体来说，如果用户请求的 URI 和这个 location 定义的字符串完全相同，但缺少了末尾的斜杠**，Nginx 会自动返回一个 301 永久重定向，将请求重定向到带有斜杠的完整 URI。

location /some_app/ { # 注意这里是以斜杠结尾的
    proxy_pass http://backend_server;
}

用户请求：http://yourdomain.com/some_app (缺少末尾的斜杠)

Nginx 的行为：Nginx 会检测到这个请求与 location /some_app/ 匹配，但是请求 URI 缺少了末尾的斜杠，并且这个 location 内部使用了 proxy_pass。

结果：Nginx 会自动向客户端返回一个 301 永久重定向，告诉浏览器应该访问 http://yourdomain.com/some_app/。

浏览器行为：浏览器收到 301 重定向后，会自动发起一个新的请求到 http://yourdomain.com/some_app/，然后这个请求才会真正被 proxy_pass 处理并转发到后端服务器。

如果不希望这样做，可以像下面这样定义URI和位置的精确匹配：

location /user/ {
    proxy_pass http://user.example.com;
}

location = /user {
    proxy_pass http://login.example.com;
}

root

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

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

/data/w3/i/top.gif文件将作为对/i/top.gif请求的响应被发送。

path的值可以包含除$document_root和$realpath_root之外的变量。

文件的路径只需要在root指令的值上添加一个URI即可。如果必须修改URI，则应该使用alias指令。

server

设置虚拟服务器的配置信息。基于IP（基于IP地址）和基于名称（基于“Host”请求头字段）的虚拟服务器之间没有明确的区分。相反，listen指令描述应该接受服务器连接的所有地址和端口，server_name指令列出所有服务器名称。示例配置在“nginx如何处理请求”文档中提供。

server_name

设置虚拟服务器的名称，例如：

复制

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

第一个名称成为主服务器的名称。

服务器名称可以包含一个星号（“*”）来代替名称的第一部分或最后一部分：

复制

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

也可以在服务器名中使用正则表达式，在名称前加上波浪号（” ‘~ ”）：

server {
    server_name www.example.com ~^www\d+\.example\.com$;
}

正则表达式可以包含捕获，稍后可以在其他指令中使用：

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

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

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

正则表达式中的命名捕获创建变量，稍后可以在其他指令中使用：

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

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

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

如果指令的参数设置为“$hostname”（0.9.4），则插入机器的主机名。

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

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

它允许此服务器处理给定地址：端口对的请求，而不是默认服务器，而不需要“Host”头字段。这是默认设置。

try_files

文件路径的构建：

• 文件路径是根据 file 参数，结合 Nginx 的 root 和 alias 指令来构建的。
• root 指令：如果你的 location 块中定义了 root，那么 Nginx 会将 root 指定的路径与请求的 URI（或 file 参数）拼接起来查找文件。
• alias 指令：如果使用了 alias，它会替换 URI 的一部分，然后与 file 参数拼接来查找文件。

按指定顺序检查文件是否存在：

• Nginx 会按照你给定的顺序，逐一检查指定的文件。
• 它会使用第一个找到的文件来处理当前请求。这意味着一旦找到一个匹配的文件，就不会再检查后续的文件了。

检查目录的存在性：

• 你不仅可以检查文件的存在，还可以检查目录是否存在。
• 方法很简单，只需要在文件名后面加上一个斜杠（/），例如 "课题/项目/我的项目/"。这通常用于判断某个目录是否存在，以便进行后续处理（例如，如果目录存在，就使用 index 或 autoindex）。

如果所有文件都未找到：

• 这是关键点：如果列表中指定的所有文件或目录都没有找到，Nginx 会执行一个内部重定向到你在最后一个参数中指定的 uri。
• 这是一个内部重定向，意味着 Nginx 不会向客户端发送 301/302 状态码，而是自己内部将请求的 URI 修改为指定的值，然后重新处理这个新的 URI。这可能会导致请求被不同的 location 块处理（如果新的 URI 匹配了不同的 location）。

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

location = /images/default.gif {
    expires 30s;
    #这个指令设置了 HTTP 响应头中的 Expires 和 Cache-Control 字段。
它告诉客户端（浏览器）和代理服务器：/images/default.gif 这个文件可以被缓存，并且在30 秒内都是有效的。
在 30 秒内，客户端再次请求同一个文件时，可以直接使用本地缓存而无需再次向服务器请求，从而提高加载速度和减轻服务器压力。
}

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

location / {
    try_files $uri $uri/index.html $uri.html =404;
}

location / {
    try_files /system/maintenance.html
              $uri $uri/index.html $uri.html
              @mongrel;
}

location @mongrel {
    proxy_pass http://mongrel;
}

在下面的例子中

location / {
    try_files $uri $uri/ @drupal;
}

try_files 指令与下面相同意思：

location / {
    error_page 404 = @drupal;
    log_not_found off;
}

types

将文件名扩展名映射到响应的MIME类型。扩展不区分大小写。几个扩展可以映射到一个类型，例如：

types {
    application/octet-stream bin exe dll;
    application/octet-stream deb;
    application/octet-stream dmg;
}

一个足够完整的映射表在nginx的conf/mime. py 文件中分发。类型的文件。

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

复制

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

嵌入变量

ngx_http_core_module模块支持与Apache服务器变量名称匹配的嵌入变量。首先，这些是代表客户端请求首部字段的变量，例如$http_user_agent、$http_cookie等。还有其他变量：