Nginx基础教程（36）Nginx HTTP请求处理之状态码：Nginx状态码“黑话”大全——别让你的网站当“哑巴”！

原创于 2025-11-28 12:16:24 发布 · 59 阅读

2 ·

CC 4.0 BY-SA版权

文章标签：

#nginx #http #运维

Nginx基础教程专栏收录该内容

36 篇文章

订阅专栏

引言：你的网站，是个“戏精”

想象一下，你走进一家咖啡馆。

服务员对你微微一笑，递上菜单——这是 200 OK，一切完美。
你点了一杯“龙息辣椒特调”，服务员一脸懵圈地看着你——这是 404 Not Found，你要的东西没有。
你刚想发火，服务员说：“稍等，我去问问我们首席调酒师”——然后他一去不回，你等到天荒地老——这是 504 Gateway Timeout。
最后，服务员跑回来，哭丧着脸说：“抱歉，调酒师被辣晕过去了，本店暂时歇业”——这是 502 Bad Gateway。

看出来了吗？每一次交互，都有一个无形的“状态码”在传递信息。你的网站，就是这个戏精服务员。而Nginx，就是决定这场戏怎么演的幕后导演。今天，咱不整那些枯燥的官方文档，就来唠唠怎么让咱家这个“服务员”更会来事儿，把坏消息说得婉转，把好消息传达得漂亮！

第一章：状态码——互联网的“摩斯密码”

状态码，说白了就是服务器对浏览器说的一句三字经。它藏在每次请求的“信封”里，你看不见，但它决定了页面的生死。

这三位数，第一位是“派系”：

1xx（信息派）：“哥们儿，我收到了，正处理呢，别急哈~”（比较少见，通常自动处理了）
2xx（成功派）：“妥了！没问题！您要的东西给您准备好了！”（人人都爱）
3xx（折腾派）：“哎呦，您要找的地儿搬了，我带您去新地址~”（重定向， SEO 关键！）
4xx（甩锅派）：“客官，这您可就不讲武德了哈，是您搞错了地址/权限不够啊！”（客户端错误）
5xx（背锅派）：“大哥…我…我这边后院起火了，您稍等会儿行不？”（服务器错误，最该警惕的）

Nginx 作为流量守门员，它既能原封不动地传递后端（如 PHP、Python 应用）的状态码，也能自己生成状态码，更牛逼的是，它还能“篡改”状态码，进行二次创作！

第二章：成功与折腾的艺术（2xx & 3xx）

2xx 系列：皆大欢喜

200 OK：互联网世界最动听的情话。意味着请求成功，资源已经妥妥地放在响应体里给你送过去了。Nginx 在成功处理静态文件或将动态请求代理到正常工作的后端时，就会返回这个。

3xx 系列：兜兜转转还是你

这个系列是 SEO 和用户体验的重中之重，玩不好就是“鬼打墙”。

301 Moved Permanently：永久搬家。 这是告诉浏览器和搜索引擎：“老铁，这个地址以后再也不用了，彻底搬到新家了，以后请直接去新家找我，顺便更新下你的书签。” 权重会传递到新URL。
302 Found：临时串门。 “嗨，您找的东西在我这儿，但只是临时放一下，主地址没变，下次您还是去老地方找。” 搜索引擎不会传递权重。

【Nginx 实战秀】如何用 Nginx 玩转重定向？

假设你的网站改版了，原来的 /old-page.html 永久移到了 /new-page.html。

server {
    listen 80;
    server_name yoursite.com;

    # 最直接的 301 重定向
    location /old-page.html {
        return 301 /new-page.html;
    }

    # 如果你想整个目录都搬走
    location /old-blog/ {
        return 301 https://yoursite.com/new-blog/;
    }

    # 甚至可以用正则表达式玩花的：把 /product-123 重定向到 /products/123.html
    location ~* ^/product-(\d+)$ {
        return 301 /products/$1.html;
    }
}

看，return 指令就是Nginx里的“传送门”，说送走就送走。

第三章：当客户“手滑”时（4xx 系列）

这个系列是客户端（通常是浏览器）的锅，但一个优秀的网站，会把锅接得优雅。

400 Bad Request：“你发的这是个啥？我解析不了！”—— 通常是请求报文格式错误。
401 Unauthorized：“请出示一下你的身份证。”—— 需要身份认证。
403 Forbidden：“你有身份证，但这个区域禁止入内。”—— 身份认证通过了，但权限不够。Nginx 经常在用户试图访问一个被 deny all 规则保护的路径，或者访问一个没有默认首页（如 index.html）且目录列表被关闭的目录时返回这个。
404 Not Found：互联网的“都市传说”。“您找的页面可能去了另一个维度。”—— 资源不存在。这是最常被自定义的状态码。

【Nginx 实战秀】把404页面变成你的“段子展示区”

默认的404页面丑爆了，而且毫无帮助。我们来给它整容！

server {
    listen 80;
    server_name yoursite.com;

    # 定义错误页面，/404.html 是你自己设计的炫酷页面路径
    error_page 404 /404.html;

    # 确保这个自定义404页面本身不会被返回404！
    location = /404.html {
        internal; # 这个页面只能由Nginx内部使用，用户不能直接访问
        root /usr/share/nginx/html; # 页面所在的目录
    }

    # 举个例子，如果你的静态资源没了，也返回友好的404
    location ~* \.(jpg|jpeg|png|gif|css|js)$ {
        # 如果文件找不到，不会直接显示nginx默认404，而是走上面定义的 error_page 规则
        # 当然，你也可以在这里单独为图片定义另一个404图片，比如一个“图片走丢了”的占位图
        # error_page 404 /images/notfound.jpg;
    }
}

你的 /usr/share/nginx/html/404.html 可以设计成这样：

<!DOCTYPE html>
<html>
<head>
    <title>哦豁！页面没找到！</title>
    <style>/* 这里放上酷炫的CSS */</style>
</head>
<body>
    <h1>🤯 404 - 知识盲区</h1>
    <p>您寻找的页面可能被外星人劫持了，或者它从来就没存在过。</p>
    <img src="/images/astronaut-cat.jpg" alt="宇航员猫">
    <p><a href="/">点击我，返回地球（首页）</a></p>
</body>
</html>

这样一来，用户即使迷路了，也会被你的幽默感安抚，而不是直接关掉页面。

第四章：当服务器“扑街”时（5xx 系列）

这是最需要我们警惕和优雅处理的系列，因为它们是你的“后院”。

500 Internal Server Error：“我…我好像搞砸了。”—— 后端应用（如PHP、Python）抛出了未捕获的异常。Nginx 只是传话筒。
502 Bad Gateway：程序员摸鱼警告！ “我联系不上后面的‘大佬’（后端应用服务器）了。”—— 当 Nginx 作为反向代理时，它无法从上游服务器（Upstream Server）收到响应。原因可能是：后端服务没启动、挂了、或者端口不对。
503 Service Unavailable：“客满，限流中。”—— 服务器暂时无法处理请求，通常是因为过载或正在维护。这是一个“礼貌的拒绝”，告诉爬虫和用户稍后再试。
504 Gateway Timeout：“后面那位‘大佬’太磨叽了，我等不及了。”—— Nginx 在等待上游服务器响应时超时了。

【Nginx 实战秀】给“扑街”的服务端穿上得体寿衣

场景1：优雅处理502/504错误

当后端PHP-FPM或者你的Node.js应用崩溃时，别让用户看到冰冷的 502 Bad Gateway。

# 首先，定义上游服务器
upstream backend {
    server 127.0.0.1:9000; # 比如 PHP-FPM
    server 127.0.0.1:3000 backup; # 或者你的Node.js应用，作为备份
}

server {
    listen 80;
    server_name yoursite.com;

    # 定义一个精美的50x错误页面
    error_page 500 502 503 504 /50x.html;
    location = /50x.html {
        internal;
        root /usr/share/nginx/html;
    }

    location / {
        proxy_pass http://backend; # 代理到上游
        proxy_next_upstream error timeout http_500 http_502 http_503 http_504; # 定义在什么情况下尝试下一个上游服务器
        proxy_next_upstream_tries 2; # 尝试次数
        proxy_connect_timeout 2s; # 连接上游超时时间
        proxy_read_timeout 5s; # 读取上游响应超时时间

        # 如果所有上游都挂了，显示自定义的50x页面，而不是默认错误
        proxy_intercept_errors on;
    }
}

你的 /usr/share/nginx/html/50x.html 可以这样写：

<!DOCTYPE html>
<html>
<head>
    <title>服务器有点小情绪</title>
</head>
<body>
    <h1>🛠️ 系统临时工正在紧急抢修中！</h1>
    <p>我们的服务器正在经历一场“数字风暴”，工程师们正带着咖啡和键盘全力抢救。</p>
    <p>请稍安勿躁，<a href="/">点此刷新</a>试试看？</p>
    <!- - 甚至可以放上一个实时状态的链接 ->
</body>
</html>

场景2：主动返回503进行维护

网站要上线新功能，需要临时停机维护？

location / {
    # 方法一：直接对整个站点返回503
    # return 503;

    # 方法二：更优雅的方式，返回503并指向一个“维护中”的漂亮页面
    error_page 503 @maintenance;
    return 503;
}

location @maintenance {
    # 这个“维护中”页面可以放在单独的文件里
    root /usr/share/nginx/html;
    try_files /maintenance.html =503;
}

同时，在返回503时，最好带上 Retry-After 头，告诉爬虫和客户端何时再来。

location @maintenance {
    add_header Retry-After 3600; # 告诉客户端1小时后再试
    root /usr/share/nginx/html;
    try_files /maintenance.html =503;
}

终章：成为Nginx状态码“导演”的终极奥义

看到这里，你已经不再是那个只会看日志的运维小白或者后端菜鸟了。你已经晋级为网站的“情绪管理大师”和“用户体验设计师”。

我们来回顾一下核心思想：

心中有数：时刻监控日志中的非200状态码，特别是5xx，它们是系统健康的晴雨表。
主动干预：不要满足于默认行为。用 error_page、return、rewrite 等指令主动管理状态码。
化险为夷：把每一个错误状态都视为一次与用户沟通的机会。一个有趣的404页面，一个安抚人心的502页面，远比冷冰冰的默认错误更能留住用户。
SEO意识：正确使用 301 和 302，管理好网站的“门牌号”，让搜索引擎蜘蛛畅通无阻。

Nginx 给了我们一套强大的工具集，让我们能够精细地控制网站与世界的每一次对话。熟练运用这些关于状态码的技巧，就如同给你的网站配备了一位24小时在线的、情商满分的金牌客服。现在，就去你的服务器上试试吧，让你的网站“会说话”！