ngx_http_rewrite_module 技术指南

一、核心指令

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

二、执行流程

1. Server 级：首先执行 http{} → server{} 范围内的所有重写模块指令，按配置顺序。
2. Location 级：依请求 URI 再次匹配 location，执行该层级重写指令。
3. 循环重写：若 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 重写、用户分流、访问控制与简易重定向，确保请求到达后端时满足预期路径和参数要求。