路由处理程序

路由处理程序允许您使用 Web请求 和 响应 APIs 为指定的路由创建自定义请求处理程序。

您需要知道: 路由处理程序仅在app目录内部可用。它们等同于pages目录中的API Routes，意味着您不需要将 API Routes 和 Route 处理程序一起使用。

公约

在app目录的route.js|ts 文件中定义路由处理程序：

export async function GET(request: Request) {}

export async function GET(request) {}

类似于page.js 和 layout.js，可以在任何app目录中嵌套路由处理程序。但是 route.js 文件不能和 page.js 在同一个路由段级别。

支持 HTTP 方法

支持下列HTTP 方法: GET, POST, PUT, PATCH, DELETE, HEAD, 和 OPTIONS。如果调用了不受支持的方法，Next.js 将会 return不被支持的405响应。

扩展了的 NextRequest 和 NextResponse APIs

除了支持原有的请求 和 响应 APIs, Next.js 用NextRequest 和 NextResponse扩展它们来为高级用例提供方便的帮手。

行为

缓存

默认情况下，不会缓存路由处理程序。然而，您能够对GET方法进行缓存。要做到这一点, 请在路由处理文件中使用路由配置选项，如export const dynamic = 'force-static'。

export const dynamic = "force-static";

export async function GET() {
  const res = await fetch("https://data.mongodb-api.com/...", {
    headers: {
      "Content-Type": "application/json",
      "API-Key": process.env.DATA_API_KEY,
    },
  });
  const data = await res.json();

  return Response.json({ data });
}

export const dynamic = "force-static";

export async function GET() {
  const res = await fetch("https://data.mongodb-api.com/...", {
    headers: {
      "Content-Type": "application/json",
      "API-Key": process.env.DATA_API_KEY,
    },
  });
  const data = await res.json();

  return Response.json({ data });
}

特殊的路由处理程序

默认情况下，特殊的路由处理程序，如： sitemap.ts, opengraph-image.tsx, 和 icon.tsx, 以及其它的 metadata 文件 保持静态，除非它们使用动态函数或动态配置选项。

路由解析

您可以将route视为最底层的路由基础。

• 它们不参与布局或像page.js的客户端导航。
• 同一个路由上不能有route.js文件和page.js.

Page	Route	Result
app/page.js	app/route.js	❌ Conflict
app/page.js	app/api/route.js	✔️ Valid
app/[user]/page.js	app/api/route.js	✔️ Valid

每个route.js 或 page.js 文件都接管该路由的所有 HTTP verbs。

export default function Page() {
  return <h1>Hello, Next.js!</h1>;
}

// ❌ Conflict
// `app/route.js`
export async function POST(request) {}

例子

下列例子展示如何将路由处理程序和其它的 Next.js APIs 和特色结合使用。

重新验证缓存数据

您可以使用next.revalidate选项重新验证缓存数据:

export async function GET() {
  const res = await fetch("https://data.mongodb-api.com/...", {
    next: { revalidate: 60 }, // Revalidate every 60 seconds
  });
  const data = await res.json();

  return Response.json(data);
}

export async function GET() {
  const res = await fetch("https://data.mongodb-api.com/...", {
    next: { revalidate: 60 }, // Revalidate every 60 seconds
  });
  const data = await res.json();

  return Response.json(data);
}

或者, 您可以使用revalidate段配置选项:

export const revalidate = 60;

Dynamic Functions

路由处理程序可以和 Next.js 的 dynamic functions 一起使用, 像 cookies 和 headers。，

Cookies

您能够读取或设置next/headers中的cookies。可以在路由处理程序中直接调用或在其它函数中嵌套这个服务器函数。

或者, 您能够使用Set-Cookie header，返回一个新的 Response。

import { cookies } from "next/headers";

export async function GET(request: Request) {
  const cookieStore = cookies();
  const token = cookieStore.get("token");

  return new Response("Hello, Next.js!", {
    status: 200,
    headers: { "Set-Cookie": `token=${token.value}` },
  });
}

import { cookies } from "next/headers";

export async function GET(request) {
  const cookieStore = cookies();
  const token = cookieStore.get("token");

  return new Response("Hello, Next.js!", {
    status: 200,
    headers: { "Set-Cookie": `token=${token}` },
  });
}

您可以使用底层的 Web APIs 来读取(NextRequest)request 中的 cookies：

import { type NextRequest } from "next/server";

export async function GET(request: NextRequest) {
  const token = request.cookies.get("token");
}

export async function GET(request) {
  const token = request.cookies.get("token");
}

Headers

你能够使用next/headers中的headers来读取 headers。可以在路由处理程序中直接调用或在其它函数中嵌套这个服务器函数。

headers实例是只读的。为了设置 headers,您需要使用 new headers返回一个新的Response。

import { headers } from "next/headers";

export async function GET(request: Request) {
  const headersList = headers();
  const referer = headersList.get("referer");

  return new Response("Hello, Next.js!", {
    status: 200,
    headers: { referer: referer },
  });
}

import { headers } from "next/headers";

export async function GET(request) {
  const headersList = headers();
  const referer = headersList.get("referer");

  return new Response("Hello, Next.js!", {
    status: 200,
    headers: { referer: referer },
  });
}

您也可以使用底层的 Web APIs 来读取(NextRequest)request 中的 headers:

import { type NextRequest } from "next/server";

export async function GET(request: NextRequest) {
  const requestHeaders = new Headers(request.headers);
}

export async function GET(request) {
  const requestHeaders = new Headers(request.headers);
}

Redirects

import { redirect } from "next/navigation";

export async function GET(request: Request) {
  redirect("https://nextjs.org/");
}

import { redirect } from "next/navigation";

export async function GET(request) {
  redirect("https://nextjs.org/");
}

动态路由段

我们推荐您阅读自定义路由页面后再继续。

路由处理程序可以使用动态段 创建来自动态数据的请求处理程序。

export async function GET(
  request: Request,
  { params }: { params: { slug: string } }
) {
  const slug = params.slug; // 'a', 'b', or 'c'
}

export async function GET(request, { params }) {
  const slug = params.slug; // 'a', 'b', or 'c'
}

Route	Example URL	params
app/items/[slug]/route.js	/items/a	{ slug: 'a' }
app/items/[slug]/route.js	/items/b	{ slug: 'b' }
app/items/[slug]/route.js	/items/c	{ slug: 'c' }

URL 查询参数

传递到路由处理程序的请求对象是一个NextRequest 实例, 它有 一些额外的便捷方式, 包括更轻松地处理查询参数。

import { type NextRequest } from "next/server";

export function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const query = searchParams.get("query");
  // query is "hello" for /api/search?query=hello
}

export function GET(request) {
  const searchParams = request.nextUrl.searchParams;
  const query = searchParams.get("query");
  // query is "hello" for /api/search?query=hello
}

流

流通常与 Large Language Models (LLMs)结合使用, 例如用于人工智能生成的内容 OpenAI。了解更多有关AI SDK.

import { openai } from "@ai-sdk/openai";
import { StreamingTextResponse, streamText } from "ai";

export async function POST(req) {
  const { messages } = await req.json();
  const result = await streamText({
    model: openai("gpt-4-turbo"),
    messages,
  });

  return new StreamingTextResponse(result.toAIStream());
}

import { openai } from "@ai-sdk/openai";
import { StreamingTextResponse, streamText } from "ai";

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = await streamText({
    model: openai("gpt-4-turbo"),
    messages,
  });

  return new StreamingTextResponse(result.toAIStream());
}

这些摘要使用 Web APIs 创建流。 您也可以直接使用底层 Web APIs 创建。

// https://developer.mozilla.org/docs/Web/API/ReadableStream#convert_async_iterator_to_stream
function iteratorToStream(iterator: any) {
  return new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next();

      if (done) {
        controller.close();
      } else {
        controller.enqueue(value);
      }
    },
  });
}

function sleep(time: number) {
  return new Promise((resolve) => {
    setTimeout(resolve, time);
  });
}

const encoder = new TextEncoder();

async function* makeIterator() {
  yield encoder.encode("<p>One</p>");
  await sleep(200);
  yield encoder.encode("<p>Two</p>");
  await sleep(200);
  yield encoder.encode("<p>Three</p>");
}

export async function GET() {
  const iterator = makeIterator();
  const stream = iteratorToStream(iterator);

  return new Response(stream);
}

// https://developer.mozilla.org/docs/Web/API/ReadableStream#convert_async_iterator_to_stream
function iteratorToStream(iterator) {
  return new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next();

      if (done) {
        controller.close();
      } else {
        controller.enqueue(value);
      }
    },
  });
}

function sleep(time) {
  return new Promise((resolve) => {
    setTimeout(resolve, time);
  });
}

const encoder = new TextEncoder();

async function* makeIterator() {
  yield encoder.encode("<p>One</p>");
  await sleep(200);
  yield encoder.encode("<p>Two</p>");
  await sleep(200);
  yield encoder.encode("<p>Three</p>");
}

export async function GET() {
  const iterator = makeIterator();
  const stream = iteratorToStream(iterator);

  return new Response(stream);
}

请求体

您可以使用标准的 Web API 方法来读取请求体：

export async function POST(request: Request) {
  const res = await request.json();
  return Response.json({ res });
}

export async function POST(request) {
  const res = await request.json();
  return Response.json({ res });
}

请求体 FormData

您可以使用request.formData() function 来读取FormData:

export async function POST(request: Request) {
  const formData = await request.formData();
  const name = formData.get("name");
  const email = formData.get("email");
  return Response.json({ name, email });
}

export async function POST(request) {
  const formData = await request.formData();
  const name = formData.get("name");
  const email = formData.get("email");
  return Response.json({ name, email });
}

因为 formData 数据都是字符串, 您可能想用zod-form-data 来按照您偏好的形式验证请求和检索数据 (例如number)。

CORS

您可以使用标准的 Web API 方法为特定的路由处理程序设置 CORS headers。

export async function GET(request: Request) {
  return new Response("Hello, Next.js!", {
    status: 200,
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type, Authorization",
    },
  });
}

export async function GET(request) {
  return new Response("Hello, Next.js!", {
    status: 200,
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type, Authorization",
    },
  });
}

您需要知道:

• 为了向多个路由处理程序添加 CORS headers, 您可以使用Middleware 或next.config.js 文件。
• Alternatively, see our CORS example package.

Webhooks

您可以使用路由处理程序来接收第三方服务的 webhooks。

export async function POST(request: Request) {
  try {
    const text = await request.text();
    // Process the webhook payload
  } catch (error) {
    return new Response(`Webhook error: ${error.message}`, {
      status: 400,
    });
  }

  return new Response("Success!", {
    status: 200,
  });
}

export async function POST(request) {
  try {
    const text = await request.text();
    // Process the webhook payload
  } catch (error) {
    return new Response(`Webhook error: ${error.message}`, {
      status: 400,
    });
  }

  return new Response("Success!", {
    status: 200,
  });
}

最主要的是, 不同于使用 Pages router 的 API Routes, 您无需使用bodyParser做任何其它配置。

非 UI 响应

您可以使用路由处理程序返回非 UI 的内容。请注意sitemap.xml, robots.txt, app icons, 和 open graph images都具有内置支持。

export async function GET() {
  return new Response(
    `<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">

<channel>
  <title>Next.js Documentation</title>
  <link>https://nextjs.org/docs</link>
  <description>The React Framework for the Web</description>
</channel>

</rss>`,
    {
      headers: {
        "Content-Type": "text/xml",
      },
    }
  );
}

export async function GET() {
  return new Response(`<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">

<channel>
  <title>Next.js Documentation</title>
  <link>https://nextjs.org/docs</link>
  <description>The React Framework for the Web</description>
</channel>

</rss>`);
}

段配置选项

路由处理程序使用与页面和布局相同的路由段配置。

export const dynamic = "auto";
export const dynamicParams = true;
export const revalidate = false;
export const fetchCache = "auto";
export const runtime = "nodejs";
export const preferredRegion = "auto";

export const dynamic = "auto";
export const dynamicParams = true;
export const revalidate = false;
export const fetchCache = "auto";
export const runtime = "nodejs";
export const preferredRegion = "auto";

参阅API reference获取更多信息。