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

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];

关键点：

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

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

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

1. 路径前缀替换：把 /api/v1/xxx 改为 /v1/xxx

   rewrite ^/api/(.*)$ /$1 break;

2. 带参数的路径重写：将 /article/123 映射为 /index.php?id=123

   rewrite ^/article/(d+)$ /index.php?id=$1 last;

3. 强制 HTTPS + 去除 www（需配合 if，注意 if 在 location 外慎用）

   if ($host = 'www.example.com') { rewrite ^(.*)$ https://example.com$1 permanent; }

4. 静态资源路径规范化：统一添加 /static/ 前缀

   location /img/ { rewrite ^/img/(.*)$ /static/img/$1 break; }

rewrite 执行时机与 location 匹配关系

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

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

调试与验证 rewrite 是否生效

rewrite 行为不易直观观察，建议结合以下方式验证：

1. 启用 error_log /path/to/log notice;，rewrite 过程会在日志中记录（需注意日志级别）
2. 用 curl -I 查看响应头中的 Location（对 redirect/permanent 生效）
3. 在目标 location 中加 add_header X-Rewritten-URI "$request_uri";，检查响应头确认最终 URI
4. 测试时优先用 return 200 "$request_uri"; 替代真实后端，快速验证 URI 变化