Nginx rewrite配置规则

作为一个被广泛用于反向代理的高性能WEB服务器，Nginx通常处于承接网站流量的最前端。在实际项目中，经常会用Nginx对特定的客户端请求做改写（即rewrite）后返回或将改写后的request_url传给后端real server做业务逻辑的处理。

本文是对nginx rewrite规则的学习笔记，参考资料主要来自官方文档。

1. Nginx rewrite配置语法说明

Syntax:  rewrite regex replacement [flag];
Default: —
Context: server, location, if

上面是Nginx文档对rewrite语法规则的说明，可知rewrite配置由4部分构成：

1）关键字rewrite表明这是一个rewrite规则

2）正则表达式regex用于筛选满足regex条件的client request uri

3）replacement用于替换uri中命中regex模式的部分

4）可选参数flag用于控制Nginx对满足本条rewrite规则的uri的后续处理行为

还可看到，rewrite配置可以位于server或location区块（一个典型的Nginx配置文件通常由http ==> server ==> location三个层级构成），还可以与if条件语法结合使用。

备注：Nginx的if配置项在使用不当时会引发诡异行为（可参考nginx wiki的If Is Evil这篇文章），通常不推荐新手使用。

2. rewrite规则的具体行为

rewrite的语法规则比较简单，但实际配置中，细节才会决定最终的rewrite行为是否符合我们的预期。

下面是对Nginx rewrite行为的详细说明，只有真正意识到可能存在的坑并搞懂这些规则细节，才能真正驾驭rewrite配置。

1）若request uri与rewrite指定的regex匹配成功，则匹配的部分会被nginx用replacement替换

2）若同一个配置区块存在多条rewrite规则，则nginx会按这些rewrite规则在配置文件的出现顺序对request uri进行匹配

3）借助flag参数可控制nginx对命中当前rewrite规则且改写后的新uri的后续处理行为，具体规则如下：

a. flag = last表示uri rewrite完成后就跳出本区块，然后根据rewrite后的新uri重新搜索符合条件的location区块。可见，nginx对client request的处理流程会继续向后走。所以，可能存在这种情况：新uri又匹配到了同一个区块，从而导致死循环（事实上，nginx最多会循环10次）！这个坑在实际配置中一定要注意。

b. flag = break表示uri rewrite完成后就跳出本区块，并且nginx会直接将rewrite后的新uri返回，也即，nginx对uri的处理已完成，不会再继续用改写后的uri匹配其他location区块。

c. flag = redirect表示nginx会返回一个http状态码为302的临时重定向url，适用于本条rewrite配置的replacement部分不以http或https开头的场合。

d. flag = permanent表示nginx会返回一个http状态码为301的永久重定向url。

4）若replacement部分包含新的请求参数，则原uri的请求参数会追加在replacement包含的请求参数之后；若不希望原uri参数被追加，则可以”?”作为replacement的结尾来阻止追加行为，示例如下：

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

5）若regex部分包含“}”或“;”，则整个表达式都必须用单引号或双引号括起来

以上规则中，flag参数的行为需要重点关注，尤其是last和break的区别。

3. 参考资料

Nginx Doc: rewrite

Nginx Doc: if directive

Nginx Wiki: If Is Evil