如何在Next.js 13 Server Actions中返回自定义HTTP状态码？

Next.js 13的Server Actions支持两种核心方式返回带自定义HTTP状态码的JSON响应，根据使用场景选择即可：

1. 手动构造带状态码的响应（推荐用于自定义成功/错误场景） #

通过NextResponse.json()可以直接生成包含指定状态码的JSON响应，适用于需要明确返回业务状态的场景，比如成功返回200、参数错误返回400等。

示例代码：

'use server';

import { NextResponse } from 'next/server';

export async function fetchExternalData() {
  try {
    // 模拟调用外部接口或读取数据库数据
    const externalData = await fetch('https://api.example.com/data')
      .then(res => {
        if (!res.ok) throw new Error('外部接口请求失败');
        return res.json();
      });

    // 返回带200状态码的成功响应
    return NextResponse.json(
      { success: true, data: externalData },
      { status: 200 }
    );
  } catch (err) {
    // 返回带400状态码的错误响应
    return NextResponse.json(
      { success: false, message: err instanceof Error ? err.message : '未知错误' },
      { status: 400 }
    );
  }
}

2. 抛出内置错误触发状态码（适用于标准HTTP错误场景） #

Next.js提供了notFound()、internalServerError()等内置方法，调用这些方法会自动返回对应的HTTP状态码，同时触发框架的错误处理逻辑（比如显示自定义错误页面）。

示例代码：

'use server';

import { notFound, internalServerError } from 'next/navigation';

export async function fetchItemById(itemId: string) {
  const response = await fetch(`https://api.example.com/items/${itemId}`);

  if (response.status === 404) {
    // 触发404状态码响应
    notFound();
  }

  if (!response.ok) {
    // 触发500状态码响应
    internalServerError();
  }

  const item = await response.json();
  return item;
}

客户端调用与状态码处理 #

在客户端组件中，可以通过useActionState捕获Server Actions返回的响应，获取状态码和JSON数据：

'use client';

import { useActionState } from 'react';
import { fetchExternalData } from '@/actions';

export default function DataPage() {
  const [actionResponse, formAction] = useActionState(fetchExternalData, null);

  return (
    <div>
      <form action={formAction}>
        <button type="submit">获取数据</button>
      </form>
      {actionResponse && (
        <div className="mt-4">
          <h3>响应状态码: {actionResponse.status}</h3>
          <pre className="mt-2 p-2 bg-gray-100">
            {JSON.stringify(await actionResponse.json(), null, 2)}
          </pre>
        </div>
      )}
    </div>
  );
}

注意：如果Server Actions是通过直接函数调用（而非表单action）触发，同样可以获取到返回的NextResponse对象，通过response.status和response.json()处理结果。

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