ngx_http_rewrite_module

    、if、、rewrite 和 指令将按以下顺序处理：

    • 在 server 级别下，该模块的指令按顺序执行
    • 重复执行：
      • 基于请求 URI 搜索
      • 在 location 内找的该模块的指令按顺序执行
      • 如果请求 URI 被重写，则重复循环，但不超过 。

    停止处理当前的 ngx_http_rewrite_module 指令集。

    如果在该 内指定了指令，则请求的下一步处理在该位置将继续。

    示例：

    if

    - 说明
    语法 if (condition) { ... };
    默认 ——
    上下文 server、location

    指定的 condition 求值之后，如果为 true，则执行在大括号内指定的该模块的指令，并在 if 指令内为该请求分配配置。if 指令内的配置继承自上一层的配置级别。

    condition 可以是以下任何一种：

    • 使用 = 和 != 运算符比较变量和字符串

    • 使用 ~（区分大小写的匹配）和 ~*（不区分大小写的匹配）运算符，变量将与正则表达式进行匹配。正则表达式可以包含可供以后在 $1..$9 变量中重用的捕获。反操作符 !~ 和 !~* 也可用。如果正则表达式包含 } 或 ; 字符，则整个表达式应使用单引号或双引号包围起来。

    • 使用 -f 和 !-f 运算符检查文件是否存在

    • 使用 -d 和 !-d 运算符检查目录是否存在

    • 使用 -e 和 !-e 运算符检查文件、目录或符号链接是否存在

    • 使用 -x 和 !-x 运算符检查是否为可执行文件

    示例：

    1. if ($http_user_agent ~ MSIE) {
    2.     rewrite ^(.*)$ /msie/$1 break;
    3. }
    5. if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
    6.     set $id $1;
    7. }
    9. if ($request_method = POST) {
    10.     return 405;
    11. }
    13. if ($slow) {
    14.     limit_rate 10k;
    15. }
    17. if ($invalid_referer) {
    18.     return 403;

    停止处理并将指定的 code 返回给客户端。非标准代码 444 在不发送响应头的情况下关闭连接。

    从 0.8.42 版本开始，可以指定重定向 URL（对 301、302、303、307 和 308 代码有效）或响应正文 text（对其他代码有效）。响应正文和重定向 URL 都可以包含变量。特殊情况下，可以将重定向 URL 指定为此服务器的本地 URI，在这种情况下，根据请求模式（$scheme）以及 和 port_in_redirect 指令形成完整重定向 URL。

    另外，可以将代码为 302 的临时重定向的 URL 指定为唯一参数。这样的参数应该以 http://、https:// 或 $scheme 字符串开头。URL 可以包含变量。

    在 0.7.51 版本之前只能返回以下代码：204、400、402-406、408、410、411、413、416 和 500-504。

    在 1.1.16 版本和 1.0.13 版本之前，代码 307 不被视为重定向。

    在 1.13.0 版本之前，代码 308 不被视为重定向。

    另请参见 指令。

    rewrite

    - 说明
    语法 rewrite regex replacement [flag];
    默认 ——
    上下文 server、location、if

    如果指定的正则表达式与请求 URI 匹配，则 URI 将根据 replacement 中的指定进行更改。rewrite 指令按照它们在配置文件中的出现顺序依次执行。可以使用标志来终止指令的下一步处理。如果替换以 http://、https:// 或 $scheme 开头的字符串，则处理流程将停止并将重定向返回给客户端。

    可选的 flag 参数可以是以下之一：

    • last

      停止处理当前的 ngx_http_rewrite_module 指令集并开始搜索新的 location 来匹配变更的 URI

    • break

      与 指令一样，停止处理当前的 ngx_http_rewrite_module 指令集;

    • redirect

      返回带有 302 代码的临时重定向，如果替换字符串不以 http://、https:// 或 $scheme 开头，则生效

    • permanent

    完整重定向 URL 根据请求模式（$scheme）以及 server_name_in_redirect 和 指令形成。

    示例：

    1. server {
    2.     ...
    4.     rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  last;
    5.     return  403;
    6.     ...
    7. }

    但是如果这些指令放在 /download/ 位置，last 标志应该用 break 替换，否则 nginx 会产生 10 个循环并返回 500 错误：

    如果 replacement 包含新请求参数，则先前的请求参数将最加在它们之后。如果不希望这样，可在 replacement 的末尾加上一个问号可以避免追加，例如：

    1. rewrite ^/users/(.*)$ /show?user=$1? last;

    如果正则表达式包含 } 或 ; 字符，则整个表达式应使用单引号或双引号包围。

    启用或禁用在 notice 级别将 ngx_http_rewrite_module 模块指令处理结果记录到 error_log 中。

    set

    - 说明
    语法 set $variable value;
    默认 ——
    上下文 server、location、if

    为指定的 variable 设置一个 value，value 可以包含文本、变量及其组合。

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

    ngx_http_rewrite_module 模块指令在配置阶段编译为内部指令，其在请求处理期间被解释执行。解释器是一个简单的虚拟栈机器。

    例如以下指令（directive）：

    1. location /download/ {
    2.     if ($forbidden) {
    3.         return 403;
    4.     }
    6.     if ($slow) {
    7.         limit_rate 10k;
    8.     }
    10.     rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
    11. }

    将会翻译成以下指令（instruction）：

    请注意，上面的 指令没有相关指令（instruction)，因为它与 ngx_http_rewrite_module 模块无关。这些单独配置是为 if 块创建的。如果条件成立，则为此配置分配一个请求，其中 limit_rate 等于 10k。

    指令：

    1. rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;

    如果正则表达式中的第一个斜杠放在括号内，可以让生成的指令（instruction）变得更轻：

      生成的指令如下：