NextJS纯API模式下如何自定义404错误返回JSON响应

NextJS作为纯API服务时，默认的HTML错误页面不符合接口需求，以下分两种路由系统给出具体实现方案：

一、Pages Router 方案 #

1. 全局API错误捕获（推荐） #

在pages/api目录下创建_error.js文件，该文件会捕获所有API路由的错误（包括404），返回自定义JSON响应：

export default function handler(err, req, res) {
  // 自定义错误状态码和响应结构
  const statusCode = err?.statusCode || res?.statusCode || 500;
  const errorResponse = {
    error: {
      message: err?.message || "服务器内部错误",
      code: err?.code || statusCode,
    },
  };

  res.status(statusCode).json(errorResponse);
}

2. 单个API路由内的错误处理 #

如果需要针对特定API路由做定制化处理，可在路由文件中用try-catch包裹业务逻辑：

export default function handler(req, res) {
  try {
    // 你的API业务逻辑
    if (!req.query.id) {
      throw new Error("缺少必要参数id");
    }
    res.status(200).json({ data: "请求成功" });
  } catch (err) {
    res.status(400).json({
      error: {
        message: err.message,
        code: 400,
      },
    });
  }
}

二、App Router 方案 #

1. Catch-All API路由处理404 #

在app/api目录下创建[...notFound]/route.js（命名可自定义），用于捕获所有未匹配的API请求，返回JSON格式404：

import { NextResponse } from "next/server";

export function GET() {
  return NextResponse.json(
    {
      error: {
        message: "请求的API路径不存在",
        code: 404,
      },
    },
    { status: 404 }
  );
}

// 覆盖其他请求方法（POST/PUT/DELETE等）
export function POST() {
  return GET();
}
export function PUT() {
  return GET();
}
export function DELETE() {
  return GET();
}

2. 全局API错误处理 #

利用App Router的中间件（middleware.js/middleware.ts）捕获API路由的错误，统一返回JSON：

import { NextResponse } from "next/server";

export function middleware(request) {
  try {
    // 可在此添加请求校验逻辑，或传递请求到下一个路由
    return NextResponse.next();
  } catch (err) {
    return NextResponse.json(
      {
        error: {
          message: err.message || "服务器内部错误",
          code: 500,
        },
      },
      { status: 500 }
    );
  }
}

// 指定仅对API路由生效
export const config = {
  matcher: "/api/:path*",
};

3. 单个API路由内的错误处理 #

在App Router的API路由文件中，用try-catch包裹逻辑，捕获错误后返回JSON：

import { NextResponse } from "next/server";

export async function GET(request) {
  try {
    const { searchParams } = new URL(request.url);
    const id = searchParams.get("id");
    if (!id) {
      throw new Error("参数id不能为空");
    }
    return NextResponse.json({ data: "请求成功" });
  } catch (err) {
    return NextResponse.json(
      {
        error: {
          message: err.message,
          code: 400,
        },
      },
      { status: 400 }
    );
  }
}

注意事项 #

• 确保所有API请求都被路由规则覆盖，避免触发NextJS默认的HTML错误页面
• 可根据业务需求自定义错误响应结构，比如添加type、trace_id等字段
• 若使用TypeScript，只需将文件后缀改为.ts，补充对应类型定义即可

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