Nginx rewrite重写规则详解：语法、flag与实战排查

做Nginx配置和运维这些年，rewrite重写功能是我几乎每个项目都会用到、也最常看到新人写错的地方。简单说，Nginx rewrite就是在收到请求之后、发出响应之前，把请求的URI改写成另一个URI，再决定走内部处理流程，还是告诉浏览器去新地址。它解决的核心问题其实就两类：一类是把各种旧链接整理成新结构，另一类是在不改后端代码的情况下，让同一套服务同时兼容老接口和新接口。这篇文章会从语法、执行顺序、location优先级、实际场景和坑点排查这几个维度来聊，适合刚接触Nginx的开发者，也适合配过一段Nginx但一直没把last和break彻底理清的人。看完之后，至少你遇到rewrite相关的404、循环跳转、配置不生效时，能有一个清晰的排查思路。

1. rewrite到底在解决什么问题

1.1 从一次URL迁移说起

我记得有次帮朋友迁移一个个人博客，旧的链接长这样 /index.php?id=123，新程序希望被访问成 /post/123.html。如果只改程序，那收藏夹、搜索引擎里的老链接就全部失效了。这时候可以在Nginx层用一条rewrite规则，把老地址透明地映射到新地址，用户点击旧链接，后端服务收到的是新地址，感知不到中间发生了什么。这种场景就是rewrite最日常的用法：不碰业务代码，只靠反向代理层做URL兼容。

类似的情况还会出现在系统改版、产品改名、文章分类调整、接口版本升级。你会发现，真正需要重写URL的往往不是“想调整一下链接样式”，而是“历史包袱太多，后端已经改名了，但老调用方不能全量通知”。rewrite最大的价值，就是给这些迁移过程留出缓冲期，让老流量平滑过渡到新结构。

1.2 rewrite能做什么，不能做什么

rewrite能做的事情，我归纳了几类：

• URL伪静态：比如把 /index.php?act=show&id=1 变成 /show/1.html，对搜索引擎更友好。
• 域名级跳转：访问 domain-a.com 直接301到 domain-b.com，并且保留请求路径。
• 强制定向到HTTPS：判断 $scheme 不是https时，整体重写成https地址。
• 规范化URL：统一结尾斜杠、消除多余路径、去掉index.php等。
• 改写请求URI后再转给后端：前端路径和内部后端路径不一致时，rewrite之后配合proxy_pass转发。

但它并不是万能的。rewrite不读数据库、不做业务判断，它只是基于正则表达式对字符串做改写，任何需要依赖Cookie、Session内容做复杂决策的需求，都不适合在这里做。另外，rewrite规则如果堆得太多，会占用worker进程的CPU时间，因为每一层location、每一条规则都要做正则匹配，所以能少写就少写，能放到代码层处理就放到代码层处理。还要区分一个概念：rewrite只是改写URI，如果要直接终止请求、返回某个响应，应该用return，后面我会展开讲。

2. rewrite规则的语法与执行机制

2.1 指令格式：rewrite regex replacement [flag]

rewrite的标准语法是：

nginx复制rewrite regex replacement [flag];

一条规则由三部分组成：正则表达式、替换目标URI、可选的标志位。最常见的示例：

nginx复制rewrite ^/article/(\d+)\.html$ /index.php?id=$1 last;

这里 ^/article/(\d+)\.html$ 是正则，用来匹配请求URI；/index.php?id=$1 是替换后的URI，其中 $1 引用正则里第一个括号捕获到的数字；last 是标志位，表示内部继续查找新的location。

三个部分里最容易写错的是正则和替换URI中的转义。比如 \.html 里的点号如果不转义，它会匹配任意字符，导致 /article/123xhtml 这种URL也会被命中。替换目标URI可以写相对路径，也可以写完整的URL。如果写完整的HTTP或HTTPS地址，Nginx会直接给客户端返回3xx跳转，不再内部改写，这一行为很容易被忽略。

2.2 正则匹配的核心规则

Nginx的rewrite正则默认是区分大小写的，不区分大小写需要在开头加 (?i)。常用的正则元字符有：

有一点要特别提醒新手：$1、$2 这类捕获变量，在rewrite里只能引用同一对括号里的内容，不能跨规则使用。另外，Nginx的正则匹配是“贪婪”的，如果URI中某个范围很长，(.*) 可能把后面的内容一起吃掉。遇到这种情况，需要用精确的分组或者限制范围，比如 ([^/]+) 匹配不含斜杠的段落，能很大程度上避免误匹配。

2.3 四个flag：last、break、redirect、permanent

标志位是rewrite最关键也最容易被绕晕的部分。四个flag的含义分别是：

很多人只记住了“last会重新匹配location，break不会”，但对实际场景中的差别还是拎不清。举个例子：在server块里写了一条rewrite，如果带last，它会重新进入location匹配阶段，可能进入一个新location；如果带break，它不会重新匹配location，而是留在当前server块的上下文里继续往下走。在location块内部，break更常见，因为rewrite之后通常希望直接转发，而不是转换到其它location。

需要特别注意的是，redirect和permanent不是内部改写，它们会让服务器返回3xx状态码给客户端，浏览器地址栏也会跟着变。如果replacement不是以 http://、https:// 或 $scheme 开头，Nginx会把它当作内部URI处理，即使写了redirect，也不会返回302。这一点在排查“明明配了redirect怎么没跳转”的时候，要第一个想到。

3. 实战场景：从伪静态到HTTP重定向

3.1 PC站与移动站跳转

移动端适配是rewrite最常见的业务场景之一。最简单的需求：用户用手机访问 www.example.com/post/123.html，希望自动落到 m.example.com/post/123.html。可以通过检测User-Agent来做：

nginx复制server {
    server_name www.example.com;

    if ($http_user_agent ~* "(Android|iPhone|Mobile)") {
        rewrite ^(.*)$ http://m.example.com$1 permanent;
    }
}

这里的 $1 捕获的是原始请求URI，包括开头的斜杠，比如访问 /post/123.html，变量组合出来就是 http://m.example.com/post/123.html，路径保持一致。permanent 表示永久跳转，实际业务中如果只是临时做Mobile适配，我建议先用 redirect，等验证稳定后再改成 permanent，避免搜索引擎过早把权重迁移过去。

但这个写法也存在一个隐患：if 在Nginx的location上下文中有时会引发意想不到的优先级问题，如果后面还有 try_files 或 proxy_pass，需要先在一个独立server里做跳转，再交给处理服务。我的经验是，简单的判断用if问题不大，但一旦出现复杂location组合，尽量把移动端UA判断放到单独的server或map里，降低踩坑概率。

3.2 伪静态规则改写

很多PHP程序，比如早期的一些CMS，URL长这样：/index.php?act=view&id=1。为了SEO好看，前端想被访问成 /view/1.html。这里存在两个方向：程序本身通过路由生成新格式链接，Nginx负责把新格式转换为程序能识别的 index.php 参数。配置可以写在server块中：

nginx复制location / {
    rewrite ^/view/(\d+)\.html$ /index.php?act=view&id=$1 last;
    rewrite ^/category/([a-zA-Z0-9_-]+)/?$ /index.php?act=category&cat=$1 last;
}

加 last 是因为rewrite后要重新进入location匹配，让Nginx能匹配到 location ^~ /index.php 或对应的PHP处理配置。如果这里用 break，则不会重新匹配location，后面的PHP处理流程可能压根不执行，结果会变成直接把内部URI返回给客户端，往往表现为下载文件或404。

伪静态的坑在于重写规则和目录前缀冲突。比如 /view/123.html 前面如果还有一个 location ~ \.php$ 的配置，就必须确认最终重写后的URI确实会进入PHP处理块。有时候你配置得好好的，后来加了一条正则location，把请求截胡了，排查起来特别头疼，最好的办法就是开着debug日志看rewrite阶段到底匹配到了哪一层。

3.3 配合proxy_pass的后端转发重写

在微服务或前后端分离架构里，Nginx常常承担统一入口角色。前端调用 /api/user/123，而后端Java服务的实际接口是 /backend/user/123。这个场景下可以用rewrite加proxy_pass：

nginx复制location /api/ {
    rewrite ^/api/(.*)$ /$1 break;
    proxy_pass http://backend;
}

这里的 break 非常关键。如果把它改成 last，rewrite之后Nginx会重新查找location，因为URI变成了 /user/123，可能又匹配到别的location，而不是继续走当前location的proxy_pass。写break，可以让当前location继续执行，同时内部URI已经被改写为 /user/123，后端收到的是去掉前缀的路径。

如果后端地址本身带有路径，还可以直接写在proxy_pass里，比如 proxy_pass http://backend/;，这是另一种解法。但要注意，proxy_pass 是否带URI，对最终请求路径的影响差异很大。遇到 /api 和 /backend 前缀不一致的时候，我习惯用rewrite加break，因为逻辑更直观，改动也小。

3.4 与return、try_files的配合

rewrite并不是唯一的URL处理工具，有时候搭配return比rewrite更高效。比如强制HTTP跳转到HTTPS：

nginx复制server {
    listen 80;
    server_name www.example.com;
    return 301 https://$host$request_uri;
}

这里用 return 而不是 rewrite，原因是return不需要做正则替换，性能更好，语义也更清晰。rewrite虽然也能实现，但会多走一轮正则匹配。对于“只是整站跳转、不改变路径”这种场景，优先用return。

try_files 是另一个和rewrite紧密相关的指令。典型的前端单页应用路由：

nginx复制location / {
    try_files $uri $uri/ /index.php;
}

意思是如果请求的文件或目录不存在，就内部改写到 /index.php，让后端路由处理。如果在这基础上还想兼容一堆历史URL，可以try_files配合rewrite做更复杂的逻辑。不过要记住一个原则：能不用rewrite实现的，尽量不用rewrite；必须在rewrite和return/alias/try_files之间取舍时，优先选择其他指令，因为它们更可控、更容易排查。

4. rewrite与location的纠缠关系

4.1 执行顺序与内部跳转

很多配置不生效，问题不是正则写错了，而是没有理解Nginx的执行顺序。Nginx处理请求时，会经历rewrite模块规定的两个阶段：一个是server级别的rewrite阶段，另一个是location级别的rewrite阶段。整体顺序大致是：

• 先执行server块内的rewrite指令；
• 根据当前的URI匹配location；
• 如果匹配到location，再执行location块内的rewrite指令；
• 如果rewrite带last，则用新的URI重新匹配location；
• 如果rewrite带break，则不再匹配location，直接继续执行当前location剩余指令。

这个顺序意味着，rewrite写在server块和写在location块，效果会有很大区别。比如你希望URI改写后走某个特殊文件的location，最好把rewrite放在要生效的location之前执行；如果你把rewrite写在某个location内部，改写后还希望换一个location处理，就必须用last。我曾经遇到一个系统，在server里写了 rewrite ^/(.*)$ /index.php last;，结果所有请求都被改写到/index.php，再匹配php相关location，导致静态文件全部404，最后才发现是server级rewrite把静态资源也拦截了。这类问题最恶心的地方在于语法没问题、规则也没冲突，纯粹是执行层级问题。

4.2 last与break的真正区别

用一个具体例子来对比last和break：

nginx复制location /app/ {
    rewrite ^/app/(.*)$ /backend/$1 last;
    proxy_pass http://backend;
}

location /backend/ {
    proxy_pass http://internal-backend;
}

假设请求 /app/user/1，rewrite先把URI改为 /backend/user/1。如果用last，Nginx会重新查找location，命中 location /backend/，然后把请求转发给 http://internal-backend。如果用break，Nginx不会重新查找location，而是继续当前 location /app/ 的上下文，执行后面的 proxy_pass http://backend;，此时后端收到的路径还是 /backend/user/1。

你会发现，两者的实际差异不只是“要不要重新匹配location”，更直接地影响了到底由哪个后端接收请求。很多线上事故就是从这里来的：改了一个flag，流量瞬间打到错误的服务上。因此，在写rewrite之前先想清楚目标：是要把请求交给另一个location处理，还是只在当前location里改个URI继续处理。想清楚这个，last和break就不会选错。

4.3 容易被忽略的location优先级

rewrite带last进行内部跳转时，目标URI会重新参与location匹配。这时就要熟悉Nginx的location匹配优先级：

• = 精确匹配优先级最高；
• ^~ 前缀匹配，若命中则不再检查正则；
• ~ 或 ~* 正则匹配，按在配置文件中出现的顺序匹配；
• 普通前缀匹配，按最长前缀匹配；
• 最后是 / 兜底。

我遇到过一个真实案例：网站使用了 location / { rewrite ^/goods/(\d+)$ /product/detail last; }，而精确匹配的 location = /product/detail 恰好存在。本意是让rewrite后的URI进入普通的前缀location，结果因为精确匹配优先级更高，直接落到了 location = /product/detail，处理行为和预期完全不同。这类问题不配置debug日志几乎看不出来，因为页面看起来还能访问，就是返回内容不对劲。

所以每次在rewrite里使用last时，都应该顺手检查目标URI会被哪些location命中，尤其是是否存在精确匹配或正则location。不要想当然认为“只要路径对应了，就会走到那个location”。

5. 常见问题与排查技巧实录

5.1 rewrite后出现404

rewrite后出现404，在绝大多数情况下是目标URI没有被Nginx正确路由，或者目标资源本身不存在。排查思路我建议按顺序来：

1. 先用 nginx -t 确认配置语法没问题，顺便看看有没有报“conflicting”之类警告。
2. 用 curl -I http://域名/旧地址 看实际返回的状态码和 Location 头。
3. 打开Nginx调试日志，在 nginx.conf 的 http 块加一句 error_log /var/log/nginx/debug.log debug;，然后重放请求，观察日志中rewrite阶段的匹配过程。
4. 确认rewrite后的URI是否存在对应的location或真实文件。

很多新人会用 last 重写后，发现目标文件明明在，却还是404，往往是rewrite后的URI进入了错误的location。比如后端的PHP请求没有走 location ~ \.php$，而是被静态文件匹配给吃了。这时候需要调整rewrite的书写位置，或者改target URI的路径结构，让Nginx按照预期匹配。

5.2 循环重定向

循环重定向是rewrite配置里最吓人的问题之一，表现是浏览器提示“太多重定向”。Nginx对内部重定向次数有上限，超出后会直接返回500并在日志里写 rewrite or internal redirection cycle。最常见的产生原因是：rewrite后的URI又匹配到了同一个rewrite规则，导致无限循环。

例如：

nginx复制rewrite ^/(.*)$ /index.php?r=$1 last;

如果 location / 里存在这条规则，而rewrite后的URI /index.php?r=... 在下一个location里又被类似规则匹配，就会不断重写。解决方法是：在rewrite规则前加条件，比如只对不以index.php开头的URI执行重写：

nginx复制if ($request_uri !~ ^/index\.php) {
    rewrite ^/(.*)$ /index.php?r=$1 last;
}

或者直接把rewrite写在不需要兜底的location里。外部301/302的循环更隐蔽，要检查是规则里拼接的变量带了重定向后的地址，又再次触发了跳转规则。平时配置完可以用 curl -IL 多跟踪几次，看看每次返回的Location和状态码，循环位置一目了然。

5.3 配置不生效

配置不生效，通常不是逻辑错误，而是几个低级但高频的原因。首先是修改完配置文件没有执行 nginx -s reload，或者执行了reload但worker进程没正常拉起，可以用 nginx -t 加 ps aux | grep nginx 确认。其次是正则没转义，比如 . 写成了普通点号，? 写成普通问号，导致匹配范围扩大或缩小。尤其URL里的点号、斜杠、问号，在正则里都需要特殊处理。还有一点容易被忽略：rewrite的默认匹配对象是不带参数的URI。比如请求 /index.php?id=1，rewrite匹配的是 /index.php，不会匹配问号后面的参数。想要匹配参数，必须用 $query_string 变量，或者改用 $request_uri，但 $request_uri 也会包含原始URI和参数，写法要特别注意。

另一个配置不生效的典型场景是：同一个URI在server块和location块各写了一条rewrite，前者的规则吞掉了请求，后者的规则永远执行不到。这种情况下，日志里只看到第一条rewrite，后面那条没有任何记录。我的习惯是：全局的URL规范化放server块，和具体业务耦合的改写到location块，并且尽量避免同一个请求路径同时出现在多个rewrite规则里。

5.4 性能与安全注意事项

rewrite模块用起来方便，但性能和安全性都需要关注。性能方面，正则匹配需要CPU计算，大量rewrite规则会把worker进程的CPU吃掉，尤其在高并发下。能放在location前缀匹配解决的问题，就不要用正则重写。能用 return 解决的业务跳转，就不要用rewrite。另外，建议在nginx.conf中开启：

nginx复制pcre_jit on;

这是PCRE正则的即时编译优化，对rewrite的正则匹配性能有明显提升，前提是Nginx编译时包含了PCRE JIT支持。

安全方面，要注意rewrite后的URI不要被恶意构造的正则绕过。任何涉及用户输入的捕获内容，都要确认是否会拼成攻击向量。比如把 $request_uri 控制的内容直接写进日志或跳转URL，可能会引入日志注入或开放重定向风险。还有一点，正则表达式本身也可能被滥用，过于复杂的正则在高并发下可能造成灾难性回溯，导致worker进程卡住。虽然Nginx不是所有场景都会触发这个问题，但在写嵌套很多的正则时，我建议多测试极端输入，别在线上环境里试。

另外还有版本升级问题。Nginx的rewrite模块在源码层面非常稳定，但如果你的Nginx版本跨得比较大，比如从1.16升到1.26或更高，最好用 nginx -t 和灰度流量确认一下正则行为没有变化。有些安全更新会调整默认配置，比如是否启用PCRE JIT、服务器版本号显示等，这些跟rewrite本身无关，但会影响你排查问题的方式。

一点个人体会

rewrite重写功能，用熟之后会觉得很顺手，但真正难的地方从来不是语法，而是你动手之前能不能想清楚一件事：这次改写是给Nginx内部看的，还是要让浏览器重新发起请求？内部改写用last或break，外部跳转用redirect或permanent。配置完出现404或循环跳转时，不要急着加规则，先把当前请求经过了哪些rewrite阶段、匹配到了哪个location查清楚。我个人特别喜欢用debug日志去追踪rewrite的执行路径，虽然一开始看着耗时间，但踩过的坑越多越会发现，这个步骤能省掉后面大量试错时间。如果你也是刚进入Nginx配置这个领域，建议用一个测试环境，故意写错last和break，观察两种情况的日志差异，比死记概念管用得多。