Nginx 如何在 Nginx 中使用 Rewrite 模块动态修改客户端请求的 URI 路径

作者：袖梨 2026-08-10

Nginx 的 rewrite 功能由核心模块 ngx_http_rewrite_module 提供，通过 rewrite、return、if 等指令在请求处理中动态修改 URI，支持正则匹配、捕获组引用及 last/break/redirect 等 flag 控制执行流程，常用于路径重写、HTTPS 跳转等场景。

Nginx 本身不提供独立的 “Rewrite 模块”，rewrite 功能由 ngx_http_rewrite_module 提供，是 Nginx 的核心模块之一，默认已编译启用，无需额外安装。它通过 rewrite、return、if、break 等指令，在请求处理的不同阶段动态修改 URI 路径（或重定向、终止流程），常用于 URL 规范化、版本迁移、SEO 适配等场景。

rewrite 指令的基本语法与匹配逻辑

rewrite 指令写在 server 或 location 块中，格式为：

rewrite <正则表达式> <替换目标> [flag];

关键点：

匹配对象是 当前请求的 URI（不含协议、域名、参数），例如请求 /old/path?x=1，匹配的是 /old/path
正则表达式使用 PCRE，支持捕获组（(...)），可在替换目标中用 $1、$2 引用
末尾 flag 决定后续行为：last（内部重写，重新匹配 location）、break（停止 rewrite，继续当前 location）、redirect（302 临时跳转）、permanent（301 永久跳转）
多个 rewrite 指令按顺序执行，除非被 break 或 return 中断

常见动态 URI 修改场景与写法

实际应用中，rewrite 常用于以下典型需求：

路径前缀替换：把 /api/v1/xxx 改为 /v1/xxx
rewrite ^/api/(.*)$ /$1 break;
带参数的路径重写：将 /article/123 映射为 /index.php?id=123
rewrite ^/article/(d+)$ /index.php?id=$1 last;
强制 HTTPS + 去除 www（需配合 if，注意 if 在 location 外慎用）
if ($host = 'www.example.com') { rewrite ^(.*)$ https://example.com$1 permanent; }
静态资源路径规范化：统一添加 /static/ 前缀
location /img/ { rewrite ^/img/(.*)$ /static/img/$1 break; }

rewrite 执行时机与 location 匹配关系

rewrite 不是“一次性改完就完事”，它的执行阶段和 location 匹配紧密相关：

在 server 块中写的 rewrite，发生在 初始 URI 匹配 location 之前，影响后续 location 选择
在 location 块中写的 rewrite，发生在 已匹配到该 location 后，此时 URI 已确定作用域
last 会触发 Nginx 用新 URI 重新查找匹配的 location；break 则留在当前 location 继续处理（如 proxy_pass 或 try_files）
避免无限循环：若 rewrite 后仍匹配当前规则且无 flag 控制，Nginx 默认最多执行 10 次 rewrite，超限返回 500 错误