Nginx rewrite配置规则

Posted 2022-11-25 slvher

作为一个被广泛用于反向代理的高性能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. 参考资料

1. Nginx Doc: rewrite
2. Nginx Doc: if directive
3. Nginx Wiki: If Is Evil