🌐 引言
Next.js 一直被称为 前端开发的瑞士军刀 ，但在 V13+ 的 App Router 体系中，它早已进化为 "全栈框架"。
前端跑页面，后端写 API，你一台机器就能搞定大半个微服务。
然而！
当我们满心欢喜地暴露 API 接口后，常常会被一个现实敲打：
- 前端报错了，返回却是 200？🤨
- 明明是客户端请求错了，却给出了 500？😵💫
- 用户看见的是 "Something went wrong"，但日志里却是一团浆糊？
今天，我们要聊聊 Next.js 的错误处理机制 以及 HTTP 状态码的奥义。
🔧 Next.js API Route 基础错误处理
在 Next.js (以 app/api 或老版本 pages/api 为例) 中，后端路由往往这样写：
javascript
// app/api/hello/route.js
export async function GET(req) {
try {
const data = { message: "Hello, Next.js" };
return new Response(JSON.stringify(data), { status: 200 });
} catch (error) {
return new Response(
JSON.stringify({ error: "Internal Server Error" }),
{ status: 500 }
);
}
}这里我们使用了 Response API，一个与 Web 标准齐平 的好东西。
✨ 看点：这是浏览器里 fetch 的返回体，Next.js 后端也用它，保持了无缝一致性。
🎭 错误处理的艺术：别让 500 背锅
小小科普：500 并不是万能兜底！
一个健壮的 API，需要根据场景返回不同的 HTTP 状态码。
这里来一波拟人化解释：
- 400 Bad Request 🤦
"兄弟，你传的参数我根本解析不了。" - 401 Unauthorized 🔑
"请出示证件，不带 Token 不让进。" - 403 Forbidden 🚧
"有证件也没用，你的等级不够。" - 404 Not Found 🕵️
"你找的资源根本不存在。" - 409 Conflict ⚔
"数据冲突，比如注册重复。" - 500 Internal Server Error 💥
"这真的是我的锅，我认了。" - 503 Service Unavailable 💤
"我现在很忙，稍后再来。"
🧩 Next.js 中的状态码封装
与其每次都手搓 Response，我们可以写个简单的帮助器：
scala
// utils/apiResponse.js
export function jsonResponse(data, status = 200) {
return new Response(JSON.stringify(data), {
status,
headers: { "Content-Type": "application/json" },
});
}
// utils/errors.js
export class ApiError extends Error {
constructor(status, message) {
super(message);
this.status = status;
}
}在路由里使用：
javascript
import { jsonResponse } from "@/utils/apiResponse";
import { ApiError } from "@/utils/errors";
export async function GET() {
try {
if (Math.random() > 0.5) {
throw new ApiError(400, "随机参数错误");
}
return jsonResponse({ message: "一切顺利！" }, 200);
} catch (err) {
if (err instanceof ApiError) {
return jsonResponse({ error: err.message }, err.status);
}
return jsonResponse({ error: "未知错误" }, 500);
}
}这样，错误处理就变得可控，日志清晰，前端收到的状态码也严格规范。
⚖️ 数学味的小插曲
错误处理其实可以类比于一种 映射函数：
- 输入：不同场景的异常 🎲
- 输出：对应的 HTTP 状态码 🏷 + 错误消息 💬
就像是一张"查表"的关系：
rust
错误类型 -> 状态码
参数缺失 -> 400
未登录 -> 401
权限不足 -> 403
资源没了 -> 404
代码异常 -> 500如果把用户请求看作概率分布，那错误处理其实就是 保证分布的期望值落在预期范围内 。
否则 ------ "长尾事件" 会在你最不想出问题的时候炸出来。💣
📊 一个小图：错误处理流程
markdown
请求进来 ➡️ 参数校验失败 ❌ → 返回 400
➡️ 权限校验失败 🚫 → 返回 401/403
➡️ 资源查无此人 🔍 → 返回 404
➡️ 内部异常 💥 → 返回 500
➡️ 一切顺利 ✅ → 返回 200总结一句 ：
好的错误处理 = 用户收到合理提示 + 开发者能快速排查问题。
🏁 总结
- 错误不可怕，可怕的是一切都返回 500。
- 状态码是沟通语言，前后端都要会。
- Next.js 给了足够的后端能力，合理封装响应工具函数，能让项目更优雅。
💡 最后提问：
- 你在项目里，是直接用
return new Response(...)，还是写了个"终极 API 工具箱"？ - 有没有踩过 状态码不规范 导致的线上事故？