如何为Next.js的API端点配置JSON格式的自定义错误响应？

单个API路由手动处理错误 #

针对特定API端点，直接在处理函数里捕获错误或判断资源状态，返回JSON格式的响应即可。

示例（pages/api/posts/[id].js）：

export default function handler(req, res) {
  const { id } = req.query;

  try {
    // 模拟获取数据的逻辑
    const post = getPostById(id);
    if (!post) {
      return res.status(404).json({
        error: "指定的文章不存在",
        statusCode: 404
      });
    }
    res.status(200).json(post);
  } catch (err) {
    // 生产环境可以隐藏具体错误信息，避免泄露敏感内容
    const errorMsg = process.env.NODE_ENV === "production" 
      ? "服务器内部错误" 
      : err.message;
    
    res.status(500).json({
      error: errorMsg,
      statusCode: 500
    });
  }
}

全局统一处理API错误（Pages Router） #

如果不想每个API都重复写错误逻辑，可以封装一个错误处理中间件，批量应用到所有API路由。

步骤1：创建错误处理中间件 #

新建utils/apiErrorHandler.js：

export default function apiErrorHandler(handler) {
  return async (req, res) => {
    try {
      await handler(req, res);
      // 如果未发送响应，说明请求的资源不存在
      if (!res.headersSent) {
        res.status(404).json({
          error: "API端点不存在",
          statusCode: 404
        });
      }
    } catch (err) {
      const errorMsg = process.env.NODE_ENV === "production"
        ? "服务器内部错误"
        : err.message;
      
      res.status(500).json({
        error: errorMsg,
        statusCode: 500
      });
    }
  };
}

步骤2：在API路由中使用中间件 #

import apiErrorHandler from "../../utils/apiErrorHandler";

const handler = async (req, res) => {
  // 你的API业务逻辑
  const data = await fetchSomeData();
  res.status(200).json(data);
};

export default apiErrorHandler(handler);

处理未定义的API端点（全局404 JSON响应） #

如果用户访问了不存在的API路径（比如/api/non-existent），Next.js默认会返回HTML格式的404，这可以通过Next.js中间件拦截并转换成JSON响应。

新建middleware.js：

import { NextResponse } from "next/server";

export async function middleware(request) {
  // 只处理API路由的请求
  if (request.nextUrl.pathname.startsWith("/api/")) {
    const response = await NextResponse.next();
    
    // 拦截HTML格式的404/500响应，转为JSON
    if (
      (response.status === 404 || response.status === 500) &&
      response.headers.get("content-type")?.includes("text/html")
    ) {
      const errorMsg = response.status === 404 
        ? "API端点不存在" 
        : "服务器内部错误";
      
      return new Response(JSON.stringify({
        error: errorMsg,
        statusCode: response.status
      }), {
        status: response.status,
        headers: { "Content-Type": "application/json" }
      });
    }
    return response;
  }
  return NextResponse.next();
}

Next.js 13+ App Router 方案 #

如果使用App Router的API路由（app/api/.../route.js），可以直接用NextResponse返回自定义JSON错误：

import { NextResponse } from "next/server";

export async function GET(request) {
  const { searchParams } = new URL(request.url);
  const id = searchParams.get("id");
  
  if (!id) {
    return NextResponse.json(
      { error: "缺少必要的ID参数", statusCode: 400 },
      { status: 400 }
    );
  }

  try {
    const item = await getItemById(id);
    if (!item) {
      return NextResponse.json(
        { error: "指定资源不存在", statusCode: 404 },
        { status: 404 }
      );
    }
    return NextResponse.json(item);
  } catch (err) {
    const errorMsg = process.env.NODE_ENV === "production"
      ? "服务器内部错误"
      : err.message;
    
    return NextResponse.json(
      { error: errorMsg, statusCode: 500 },
      { status: 500 }
    );
  }
}

内容的提问来源于stack exchange，提问作者Julius Jonker