【Nginx学习总结】7. Nginx rewrite模块深入浅出

关注

转载最新推荐文章于 2026-10-07 19:29:13 发布 238 阅读 AI 写同款· GEO 优化 ›

Nginx 之Rewrite 使用详解 Nginx 的rewrite模块是处理 HTTP 请求过程中的一个重要功能，它允许基于 Perl 兼容正则表达式（PCRE）对用户请求的 URI 进行重写，并返回 30x 重定向跳转或按条件执行相关配置。这个模块提供了灵活的 URL 重写和重定向功能，可以用于实现友好 URL、301/302 重定向、条件重写等。阅读详情

一、介绍

nginx通过ngx_http_rewrite_module模块支持：

（1）url重写

（2）支持if条件判断，但不支持else。

另外该模块需要PCRE支持，应在编译nginx时指定PCRE支持。根据相关变量重定向和选择不同的配置，从一个location跳转到另一个location，不过这样的循环最多可以执行10次，超过后nginx将返回500错误。

同时，重写模块包含set指令，来创建新的变量并设其值，这在有些情景下非常有用的，如

（1）记录条件标识

（2）传递参数到其他location、记录做了什么

二、Rewrite指令

1. break

Syntax: break;
Default:—
Context:server, location, if

此指令的意思是停止执行当前虚拟主机的后续rewrite指令集。

if ($slow) {
     limit_rate 10k;
     break;
}

2. if

Syntax: if (condition) { ... }
Default:—
Context:server, location

对给定的条件（condition）进行判断，如果条件为真，大括号内的rewrite指令将被执行。

条件(conditon)可以是如下任何操作：

当表达式只是一个变量时，如果值为空或任何以0开头的字符串都会当做false；
使用“=”和“!=”比较一个变量和字符串；
使用“~”做正则表达式匹配，“~*”做不区分大小写的正则匹配
使用“-f”和“!-f” 检查一个文件是否存在；
使用“-d”和“!-d”检查一个目录是否存在；
使用“-e”和“!-e”检查一个文件、目录、符号链接是否存在；
使用“-x”和“ !-x”检查一个文件是否可执行；

例子：

//如果UA包含"MSIE"，rewrite请求到/msid/目录下
if ($http_user_agent ~ MSIE) {
    rewrite ^(.*)$ /msie/$1 break;
}
//如果cookie匹配正则，设置变量$id等于正则引用部分
if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
    set $id $1;
}
 
//给某个访问IP返回403
if ( $remote_addr = "202\.38\.78\.85" ){
    return 403;
}
 
//如果提交方法为POST，则返回状态405（Method not allowed）。return不能返回301,302
if ($request_method = POST) {
    return 405;
}
 
//如果$slow可以通过set指令设置，则进行限速处理
if ($slow) {
    limit_rate 10k;
}
 
//如果请求的文件名不存在，则反向代理到localhost 。这里的break也是停止rewrite检查
if (!-f $request_filename){
    break;
    proxy_pass http://127.0.0.1;
}
 
//如果query string中包含"post=140"，则永久重定向到example.com
if ($args ~ post=140){
    rewrite ^ http://example.com/ permanent;
}
 
//防盗链
location ~* \.(gif|jpg|png|swf|flv)$ {
    valid_referers none blocked www.baidu.com www.ywnds.com;
    if ($invalid_referer) {
        return 404;
    }
}

3. return

Syntax: return code [text];
        return code URL;
        return URL;
Default:—
Context:server, location, if

停止处理并为客户端返回状态码，非标准的444状态码将关闭连接，不发送任何响应头。可以使用的状态码有：204，400，402-406，408，410, 411, 413, 416与500-504。

如果状态码附带文字段落，该文本将被放置在响应主体。

如果状态码后面是一个URL，该URL将成为location头部值。

没有状态码的URL将被视为一个302状态码。

因为301和302不能简单的只返回状态码，还必须有重定向的URL，这就是return指令无法返回301,302的原因了。

4. rewrite

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

rewrite指令的功能就是，使用nginx提供的全局变量或自己设置的变量，然后结合正则表达式和标志位实现url重写以及重定向。rewrite指令只能放在server、location或if中，并且只能对域名后边的除去传递的参数外的字符串起作用，例如 http://ywnds.com/a/we/index.php?id=1&u=str，只对/a/we/index.php重写。

如果想对域名或参数字符串起作用，可以使用全局变量匹配，也可以使用proxy_pass反向代理。

flag可以是如下参数：

last，完成该rewrite规则的执行后，停止处理后续rewrite指令集；然后查找匹配改变后URI的新location；
break，完成该rewrite规则的执行后，停止处理后续rewrite指令集，并不再重新查找；但是当前location内剩余非rewrite语句和location外的的非rewrite语句可以执行；
redirect，返回302临时重定向，地址栏会显示跳转后的地址；
permanent，返回301永久重定向，地址栏会显示跳转后的地址；即表示如果客户端不清理浏览器缓存，那么返回的结果将永久保存在客户端浏览器中了。

这里last和break区别有点难以理解：

1）last一般写在server和if中，而break一般使用在location中；

2）last不终止重写后的url匹配，即新的url会再从server走一遍匹配流程，而break终止重写后的匹配；

示例：

server {
     ...
     rewrite ^(/download/.*)/media/(.*)..*$ $1/mp3/$2.mp3 last;
     rewrite ^(/download/.*)/audio/(.*)..*$ $1/mp3/$2.ra last;
     return 403;
     ...
}

如果这些rewrite放到“/download/”路径，那么location如下所示，这时应使用break而不是last，使用last将循环10次匹配，然后返回500错误:

location /download/ {
     rewrite ^(/download/.*)/media/(.*)..*$ $1/mp3/$2.mp3 break;
     rewrite ^(/download/.*)/audio/(.*)..*$ $1/mp3/$2.ra break;
     return 403;
}

5. set

Syntax: set $variable value;
Default:—
Context:server, location, if

定义一个变量并赋值，值可以是文本，变量或者文本变量混合体。

6. rewrite_log

Syntax: rewrite_log on | off;
Default:rewrite_log off;
Context:http, server, location, if

开启或关闭以notice级别打印rewrite处理日志到error log文件。

nginx打开rewrite log的例子如下：

rewrite_log on;                        //打开rewrite log
error_log logs/xxx.error.log notice;   //把error log的级别调整为notice

三、Rewrite模块使用实例

1. 作为重写规则的一部分，传递新的查询字符串参数是使用重写规则的目标之一

rewrite ^/images/(.*)_(\d+)x(\d+)\.(png|jpg|gif)$ /resizer/$1.$4?width=$2&height=$3? last;

2. 使用rewrite模块禁止用户代理

Nginx可以通过各种方式来限制访问，例如NGINX基本Http认证、allow/deny等等，这些都是前文提过的，下面来看看nginx如何通过用户代理来禁止访问。

user agent是什么?

简单来说告诉服务器你当前使用的是什么浏览器、工具等来访问我的。例如火狐、chrome、wget、curl等浏览器或工具。使用$http_user_agent变量就可以获取到用户代理，一般在定义日志格式时都会使用这个变量，把用户代理记录到日志中去。

如何禁止特定UA？

我们不希望被使用wget或者curl来下载我的文件，怎么做呢？这里就可以使用rewrite模块了，编辑nginx配置文件。

以下内容放在http配置段，那么整个nginx都生效。如果放到server里，那么一个域名生效，你放哪，哪就有效！

if ($http_user_agent ~* (curl) ) {

return 404;

}

禁止多个UA

if ($http_user_agent ~* (wget|curl) ) {

return 404;

}

nginx重写规则说起来挺简单的，做起来就难，重点在于正则表达式，同时，还需要考虑到nginx执行顺序。

四、全局变量

$args               #这个变量等于请求行中的参数，同$query_string;
$content_length     #请求头中的Content-length字段;
$content_type       #请求头中的Content-Type字段;
$document_root      #当前请求在root指令中指定的值，如:root /var/www/html;
$host               #请求主机头字段，否则为服务器名称;
$http_user_agent    #客户端agent信息;
$http_cookie        #客户端cookie信息;
$limit_rate         #这个变量可以限制连接速率;
$request_method     #客户端请求的动作，通常为GET或POST;
$remote_addr        #客户端的IP地址;
$remote_port        #客户端的端口;
$remote_user        #已经经过Auth Basic Module验证的用户名;
$request_filename   #当前请求的文件路径，由root或alias指令与URI请求生成;
$scheme             #HTTP方法（如http，https）;
$server_protocol    #请求使用的协议，通常是HTTP/1.0或HTTP/1.1;
$server_addr        #服务器地址，在完成一次系统调用后可以确定这个值;
$server_name        #服务器名称;
$server_port        #请求到达服务器的端口号;
$request_uri        #包含请求参数的原始URI，不包含主机名，如：”/foo/bar.php?arg=baz”;
$uri                #不带请求参数的当前URI，$uri不包含主机名，如”/foo/bar.html”;
$document_uri       #与$uri相同,例：http://localhost:88/test1/test2/test.php;

例如：http://localhost:88/test1/test2/test.php这个URL，其中：

$host：localhost
$server_port：88
$request_uri：http://localhost:88/test1/test2/test.php
$document_uri：/test1/test2/test.php
$document_root：/var/www/html
$request_filename：/var/www/html/test1/test2/test.php