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 指令的执行遵循严格的顺序,理解这一点对排查问题至关重要:
server块中的rewrite指令按顺序执行。- 根据当前 URI 搜索匹配的
location。 location块中的rewrite指令按顺序执行。- 如果 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 环境验证后再上线。