当前位置：首页 > news >正文

ngx_http_rewrite_module 技术指南

news 2025/5/19 5:12:14

一、核心指令

指令	功能概述
rewrite	正则匹配并修改 URI，可带 `last`/`break`/`redirect`/`permanent` 标志
if	条件测试，成立时执行花括号内的重写/返回等指令
return	立即返回状态码或重定向
set	给用户变量赋值
break	停止当前层级的重写指令执行
rewrite_log	打开重写过程的日志
uninitialized_variable_warn	控制未初始化变量访问时的警告

二、执行流程

Server 级：首先执行 http{} → server{} 范围内的所有重写模块指令，按配置顺序。
Location 级：依请求 URI 再次匹配 location，执行该层级重写指令。
循环重写：若 rewrite 修改了 URI，最多重试 10 次上述匹配与执行流程。

三、指令详解与示例

1. `rewrite`

rewrite <regex> <replacement> [last|break|redirect|permanent];

regex：PCRE 正则，用于匹配原始 URI。
replacement：可使用 $1..$9 捕获组与内置变量。
标志：
- last：替换后重跑 location 匹配 (相当于内部 redirect)
- break：只在当前 location 继续执行，不再重匹配
- redirect：302 临时跳转
- permanent：301 永久跳转

示例：多种格式重写

# 将 /download/pkg/media/file.ext 重写到 /download/pkg/mp3/file.mp3
rewrite ^(/download/[^/]+)/media/(.+)\.\w+$ $1/mp3/$2.mp3 last;# 无附加参数时，追加旧 args：
#     /foo?x=1 → /bar?y=2&x=1
rewrite ^/foo$ /bar?y=2 last;# 若不想携带旧 args，加 ? 切断：
rewrite ^/foo$ /bar?y=2? last;

2. `if`

if (<condition>) {# 支持 rewrite, return, set, break, limit_rate 等指令
}

条件类型：
- 变量真值测试（"$var" 为空或“0”视为假）
- 字符串比较： =, !=
- 正则匹配： ~, ~*, !~, !~*
- 文件测试： -f, -d, -e, -x 及其否定

示例：User-Agent 判断与返回

# IE 浏览器定向到专用落地页
if ($http_user_agent ~* "MSIE") {rewrite ^/(.*)$ /msie.html break;
}# 禁止 POST 方法
if ($request_method = POST) {return 405 "Method Not Allowed";
}

警告：

过度复杂的 if 嵌套会导致混乱与性能问题，官方建议仅做简单条件处理；
在 location 内使用 rewrite … last，须注意可能触发多次重匹配循环。

3. `return`

# 纯状态码返回
return 404;
# 带正文
return 403 "Access Denied";
# 重定向
return 301 https://$host$request_uri;
# 302 临时跳转（URL 可直接作为单参）
return https://$host/newpath;

关闭连接：使用非标准 444 即可立刻断开，不返回任何头体。

4. `set`

set $myvar "<value>";

给自定义变量赋常量、其它变量或它们的拼接，后续可在 rewrite、proxy_pass、return 等指令中使用。

if ($http_cookie ~* "uid=([^;]+)") {set $uid $1;
}
proxy_pass http://backend/user/$uid;

5. `break`

等同于在当前上下文结束后不再执行本层剩余 rewrite 指令，但不重启 location 匹配。

location /images/ {rewrite ^/images/(.*)\.jpg$ /img/$1.png break;# 上面匹配后，不会再执行本 location 的其他 rewrite
}

四、调试与日志

开启重写日志
```
rewrite_log on;
error_log /var/log/nginx/rewrite.log notice;
```
可在 notice 级别下查到每次重写和 if 条件的执行情况。
禁止未初始化变量警告
```
uninitialized_variable_warn off;
```

通过合理使用 ngx_http_rewrite_module，可在 Nginx 层面快速实现 URL 重写、用户分流、访问控制与简易重定向，确保请求到达后端时满足预期路径和参数要求。

查看全文

http://www.xdnf.cn/news/507817.html