rewrite 是 Nginx 中 ngx_http_rewrite_module 模块的核心指令,用于基于 PCRE 正则表达式修改请求 URI、返回重定向,或按条件选择配置。它是实现 URL 规范化、旧链接迁移、伪静态等需求的关键工具。


基本语法

rewrite regex replacement [flag];
  • regex:用于匹配请求 URI 的正则表达式。
  • replacement:匹配成功后替换成的目标 URI,可包含捕获组($1–$9)或变量。
  • flag:可选标志,控制重写后的行为,决定了是“内部改写”还是“外部重定向”。

如果正则表达式中包含 } 或 ;,整个表达式需要用单引号或双引号括起来。


四个核心 Flag 的区别

这是 rewrite 最容易混淆的部分,选择正确的 flag 决定了浏览器地址栏是否变化、是否发起新请求。

Flag 浏览器地址栏 服务器行为 典型用途
last 不变 停止当前 rewrite 指令集,重新搜索新的 location 来匹配改写后的 URI 在 server 或 if 块中,将请求交给另一个 location 处理
break 不变 停止当前 rewrite 指令集,继续在当前 location 中执行后续指令 在 location 内部,仅改写 URI 但不触发新的 location 匹配
redirect 改变 返回 302 临时重定向,客户端发起新请求 临时性的 URL 变更,爬虫不会更新索引
permanent 改变 返回 301 永久重定向,客户端发起新请求 永久性的 URL 迁移,搜索引擎会更新索引

关键区别:last 和 break 是内部改写,用户无感知;redirect 和 permanent 是外部重定向,浏览器地址栏会变为新 URL。

一个重要的陷阱:如果在 location 内部使用 last,而改写后的 URI 又匹配回同一个 location,Nginx 会循环最多 10 次后返回 500 错误。此时应改用 break。


执行顺序

rewrite 指令的执行遵循严格的顺序,理解这一点对排查问题至关重要:

  1. server 块中的 rewrite 指令按顺序执行。
  2. 根据当前 URI 搜索匹配的 location。
  3. location 块中的 rewrite 指令按顺序执行。
  4. 如果 URI 被改写(且 flag 允许继续),重复第 2 步,但最多不超过 10 次。

此外,break、if、return、set 等指令也与 rewrite 同属该模块,在各自上下文中按顺序处理。


正则表达式与捕获组

rewrite 的 regex 使用 PCRE 语法,通过圆括号 () 创建捕获组,匹配到的内容可用 $1–$9 在 replacement 中引用。

位置捕获组($1–$9) 有一个关键限制:它们的值会在下一次正则匹配时被覆盖。如果需要在另一个不相关的指令中保留某个捕获值,应使用 set 立即将其保存到变量中:

location ~ ^/images/(.*)$ {
    set $saved_path $1;   # 立即保存,防止后续正则匹配覆盖 $1
    rewrite ^/images/(.*)$ /photos/$1 last;
}

命名捕获组(?<name>)则创建了普通的 Nginx 变量,不会被后续正则匹配覆盖,更适合跨指令传递捕获值:

location ~ ^/images/(?<name>.*)\.(?<ext>[a-z]+)$ {
    # $name 和 $ext 是持久变量,可在后续指令中安全使用
}

常见使用示例

示例一:旧域名永久迁移到新域名

server {
    listen 80;
    server_name old-domain.com;
    rewrite ^/(.*)$ http://new-domain.com/$1 permanent;
}

^/(.*)$ 捕获完整路径,$1 将其拼接到新域名后,permanent 返回 301,搜索引擎会更新索引。

示例二:动态 URL 伪静态化

将 /product/123 内部改写为 /index.php?id=123,地址栏保持 /product/123 不变:

location /product/ {
    rewrite ^/product/([0-9]+)$ /index.php?id=$1 last;
}

([0-9]+) 捕获数字 ID,last 将改写后的 URI 交给后续 location(如 PHP 处理块)。

示例三:隐藏文件扩展名

让用户访问 /page 时实际返回 /page.html:

location / {
    rewrite ^/([^/]+)$ /$1.html last;
}

([^/]+) 捕获不含斜杠的页面名,追加 .html 后内部转发。

示例四:使用 if 按 User-Agent 分流

if ($http_user_agent ~ MSIE) {
    rewrite ^(.*)$ /msie/$1 break;
}

当 UA 匹配 MSIE 时,将请求内部改写至 /msie/ 子目录,break 确保在当前 location 内继续处理。

示例五:保留或丢弃原始查询参数

rewrite 默认会将原请求的查询参数追加到新 URI 后面。如果新 URI 中已经自行定义了参数,不希望原参数污染,在 replacement 末尾加一个 ? 即可:

# 原参数会被追加: /show?user=alice&old=1
rewrite ^/users/(.*)$ /show?user=$1 last;

# 加 ? 丢弃原参数: /show?user=alice
rewrite ^/users/(.*)$ /show?user=$1? last;

示例六:优先使用 return 处理简单重定向

对于不需要正则捕获的简单跳转,官方推荐优先使用 return,因为它不经过 rewrite 模块的完整解析流程,性能更好:

# 推荐
return 301 https://new-domain.com$request_uri;

# 不必要地使用 rewrite(虽然能工作,但更重)
# rewrite ^ https://new-domain.com$request_uri permanent;

return 同样支持在 server 和 location 上下文中使用,是处理整站迁移、强制 HTTPS 等场景的首选。


注意事项与最佳实践

  • 优先 return,后 rewrite:仅当需要正则捕获组来构造目标 URI 时,才使用 rewrite。
  • location 内慎用 last:如果改写后的 URI 仍匹配同一 location,会触发循环并最终返回 500,此时应使用 break。
  • 用 set 或命名捕获组保存关键值:位置捕获组 $1 会在下一次正则匹配时被覆盖,跨指令使用前务必保存。
  • 简化正则:过于复杂或宽泛的正则不仅影响性能,还可能意外匹配到不该改写的请求。
  • 善用 rewrite_log on; 调试:在 server 或 location 中开启后,rewrite 的执行过程会以 notice 级别写入 error_log,便于定位规则未按预期生效的原因。
  • 生产环境前充分测试:正则的边界条件(如尾部斜杠、特殊字符)容易遗漏,务必在 staging 环境验证后再上线。