Nginx 工程实践 -- 14. 重写、重定向与 error_page
路由的"最后一公里"往往不是 location 匹配,而是在匹配前后改写 URI、决定跳哪里、出错时怎么收场。ngx_http_rewrite_module 提供 rewrite/return/if/set,error_page 负责把错误码转成友好响应或内部处理,try_files 负责静态回退。理解它们的执行顺序,是避免"改了没生效""死循环 500"的前提。
一、执行顺序
rewrite 模块指令按以下顺序处理:
- 先执行 server 级的
rewrite/if/return/set; - 按当前 URI 匹配 location;
- 执行该 location 内的同类指令;
- 若 URI 被改写,重新匹配 location,如此循环,最多 10 次,超过返回 500。
flowchart TD
A["请求 URI"] --> B["server 级 rewrite"]
B --> C["按 URI 匹配 location"]
C --> D["location 级 rewrite"]
D --> E{"URI 被改写?"}
E -- "否" --> G["内容处理 / 代理"]
E -- "是" --> F["内部重定向,计数 +1"]
F -->|"计数 ≤ 10"| C
F -->|"计数 > 10"| H["返回 500"]
因为存在"改写后重新匹配",server 级 rewrite 常配合
last,location 内改写多配合break,否则容易触发 10 次循环。
二、rewrite 与四种 flag
1 | |
| flag | 行为 |
|---|---|
last | 停止当前 rewrite 集,按新 URI 重新匹配 location(server 级常用) |
break | 停止当前 rewrite 集,留在当前 location 内继续处理(location 内常用) |
redirect | 返回 302 临时跳转(replacement 不以 http/https 开头时) |
permanent | 返回 301 永久跳转 |
示例:
1 | |
易错点:
- replacement 以
http://、https://或$scheme开头时,处理直接停止并返回跳转; - replacement 末尾加
?可丢弃原查询参数:rewrite ^/u/(.*)$ /show?user=$1? last;; - 正则里若含
}或;,整个表达式要加引号。
三、return:最直接的响应
1 | |
return比rewrite语义更清晰,做跳转/拒绝时优先用它;return 302 URL;(URL 以 http/https/$scheme 开头)可简写;- 444 常用于"不存在的域名/扫描器"直接掐连接。
四、if 与 set
if 的条件形式:变量真值、=/!=、正则 ~/~*(!~/!~* 取反)、文件/目录存在性 -f/-d/-e/-x。
1 | |
要点:
if内部只推荐return、rewrite ... break等少数用法,不要在里面堆复杂逻辑或嵌套if;- 正则捕获存入
$1..$9,可被后续指令使用; set赋值可含变量组合。
五、error_page:错误码的收场
error_page 把指定状态码转成另一段响应,可以是外部跳转或内部重定向(交给某个 location 处理):
1 | |
error_page 404 =200 /empty.gif;可改写状态码(这里把 404 变成 200);- 内部重定向的目标若是
proxy_pass/fastcgi_pass,错误处理就落到后端; - 递归上限默认 5 次,超了报
rewrite or internal redirection cycle; - 静态错误页建议加
internal,避免被直接 GET。
六、try_files:静态回退
第 1 篇已用过,这里补一个通用形态:
1 | |
按顺序尝试:文件 → 目录 → /index.html → 404。最后一项是"兜底",写 =404 可让缺失资源明确 404,而不是回退成 HTML(前端拿到 MIME 错误的响应)。
七、常见坑
| 坑 | 说明 |
|---|---|
server 级 rewrite ... break | 不会重新匹配 location,容易改完落在错误 location |
location 内 rewrite ... last | 触发重新匹配,多个 rewrite 叠加可能 10 次循环 → 500 |
if 里做复杂逻辑 | 官方只推荐 return/rewrite 等少数用法,嵌套容易出意外 |
| 查询参数被追加 | replacement 末尾加 ? 丢弃原参数 |
error_page 目标无 internal | 错误页可被直接访问,暴露内部路径 |
error_page 与 proxy_intercept_errors | 默认不拦截上游错误码,需要时显式开启(见第 10 篇) |
内部重定向后 access_log 记在哪 | 记在最终 location,不是原始 location |
参考链接
- Nginx 官方文档:ngx_http_rewrite_module —— 执行顺序、
rewriteflag、return、if、set; - Nginx 官方文档:ngx_http_core_module(error_page) —— 错误页与内部重定向、
=code改写状态; - Nginx 官方文档:ngx_http_core_module(try_files / internal);
- Nginx 官方文档:ngx_http_proxy_module(proxy_intercept_errors) —— 拦截上游错误码;
- RFC 9110:HTTP 状态码语义。
小结
- 顺序是:server 级 rewrite → 匹配 location → location 内 rewrite → 改写后重新匹配(≤10 次);
- server 级用
last,location 内用break,跳转用return更清晰; if只做简单判断(return/rewrite/limit_rate),别堆复杂逻辑;error_page做错误收场,配internal防直接访问,=code可改状态码;try_files ... =404避免缺失资源被回退成 HTML。
系列导航
Nginx 工程实践 -- 14. 重写、重定向与 error_page
https://bubao.github.io/posts/e4f5a6b7.html
