Nginx 工程实践 -- 14. 重写、重定向与 error_page

路由的"最后一公里"往往不是 location 匹配,而是在匹配前后改写 URI、决定跳哪里、出错时怎么收场。ngx_http_rewrite_module 提供 rewrite/return/if/set,error_page 负责把错误码转成友好响应或内部处理,try_files 负责静态回退。理解它们的执行顺序,是避免"改了没生效""死循环 500"的前提。

一、执行顺序

rewrite 模块指令按以下顺序处理:

  1. 先执行 server 级的 rewrite/if/return/set;
  2. 按当前 URI 匹配 location;
  3. 执行该 location 内的同类指令;
  4. 若 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
rewrite regex replacement [flag];
flag行为
last停止当前 rewrite 集,按新 URI 重新匹配 location(server 级常用)
break停止当前 rewrite 集,留在当前 location 内继续处理(location 内常用)
redirect返回 302 临时跳转(replacement 不以 http/https 开头时)
permanent返回 301 永久跳转

示例:

1
2
3
4
5
6
7
8
9
server {
# 老路径 301 到新路径,让浏览器/搜索引擎更新
rewrite ^/old/(.*)$ /new/$1 permanent;

location /download/ {
# location 内改写,用 break,避免反复重新匹配
rewrite ^/download/(.*)\.html$ /files/$1 break;
}
}

易错点:

  • replacement 以 http://、https:// 或 $scheme 开头时,处理直接停止并返回跳转;
  • replacement 末尾加 ? 可丢弃原查询参数:rewrite ^/u/(.*)$ /show?user=$1? last;;
  • 正则里若含 } 或 ;,整个表达式要加引号。

三、return:最直接的响应

1
2
3
4
5
6
7
8
# 跳转(301/302/303/307/308)
return 301 https://$host$request_uri;

# 带响应体
return 403 "Forbidden";

# 非标准码 444:直接断开,不返回任何头
return 444;
  • return 比 rewrite 语义更清晰,做跳转/拒绝时优先用它;
  • return 302 URL;(URL 以 http/https/$scheme 开头)可简写;
  • 444 常用于"不存在的域名/扫描器"直接掐连接。

四、if 与 set

if 的条件形式:变量真值、=/!=、正则 ~/~*(!~/!~* 取反)、文件/目录存在性 -f/-d/-e/-x。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 只对特定来源拒绝
if ($invalid_referer) {
return 403;
}

# 用正则捕获,取出会话 ID
if ($http_cookie ~* "sid=([^;]+)(?:;|$)") {
set $sid $1;
}

# 方法限制
if ($request_method = POST) {
return 405;
}

要点:

  • if 内部只推荐 return、rewrite ... break 等少数用法,不要在里面堆复杂逻辑或嵌套 if;
  • 正则捕获存入 $1..$9,可被后续指令使用;
  • set 赋值可含变量组合。

五、error_page:错误码的收场

error_page 把指定状态码转成另一段响应,可以是外部跳转或内部重定向(交给某个 location 处理):

1
2
3
4
5
6
7
8
9
10
11
12
server {
# 静态错误页:直接映射文件
error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;

# 内部重定向到处理逻辑(注意用 internal 防止被直接访问)
error_page 401 /auth;

location = /404.html { internal; root /var/www/errors; }
location = /50x.html { internal; root /var/www/errors; }
location = /auth { internal; proxy_pass http://127.0.0.1:3000/login; }
}
  • error_page 404 =200 /empty.gif; 可改写状态码(这里把 404 变成 200);
  • 内部重定向的目标若是 proxy_pass/fastcgi_pass,错误处理就落到后端;
  • 递归上限默认 5 次,超了报 rewrite or internal redirection cycle;
  • 静态错误页建议加 internal,避免被直接 GET。

六、try_files:静态回退

第 1 篇已用过,这里补一个通用形态:

1
2
3
4
location / {
root /var/www/dist;
try_files $uri $uri/ /index.html =404;
}

按顺序尝试:文件 → 目录 → /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

参考链接

  1. Nginx 官方文档:ngx_http_rewrite_module —— 执行顺序、rewrite flag、return、if、set;
  2. Nginx 官方文档:ngx_http_core_module(error_page) —— 错误页与内部重定向、=code 改写状态;
  3. Nginx 官方文档:ngx_http_core_module(try_files / internal);
  4. Nginx 官方文档:ngx_http_proxy_module(proxy_intercept_errors) —— 拦截上游错误码;
  5. 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
作者
一念
发布于
2026年11月21日
许可协议