route.js
route.js 特殊文件的 API 参考。
Route Handler 允许您使用 Web Request 和 Response API 为给定路由创建自定义请求处理程序。
export async function GET() {
return Response.json({ message: 'Hello World' })
}export async function GET() {
return Response.json({ message: 'Hello World' })
}参考#
HTTP 方法#
route 文件允许您为给定路由创建自定义请求处理程序。支持以下 HTTP 方法:GET、POST、PUT、PATCH、DELETE、HEAD 和 OPTIONS。
export async function GET(request: Request) {}
export async function HEAD(request: Request) {}
export async function POST(request: Request) {}
export async function PUT(request: Request) {}
export async function DELETE(request: Request) {}
export async function PATCH(request: Request) {}
// 如果未定义 `OPTIONS`,Next.js 将自动实现 `OPTIONS`,并根据 Route Handler 中定义的其他方法设置相应的 Response `Allow` 头。
export async function OPTIONS(request: Request) {}export async function GET(request) {}
export async function HEAD(request) {}
export async function POST(request) {}
export async function PUT(request) {}
export async function DELETE(request) {}
export async function PATCH(request) {}
// 如果未定义 `OPTIONS`,Next.js 将自动实现 `OPTIONS`,并根据 Route Handler 中定义的其他方法设置相应的 Response `Allow` 头。
export async function OPTIONS(request) {}参数#
request(可选)#
request 对象是一个 NextRequest 对象,它是 Web Request API 的扩展。NextRequest 让您可以进一步控制传入的请求,包括轻松访问 cookies 以及扩展的、经过解析的 URL 对象 nextUrl。
import type { NextRequest } from 'next/server'
export async function GET(request: NextRequest) {
const url = request.nextUrl
}export async function GET(request) {
const url = request.nextUrl
}context(可选)#
params:一个 promise,解析为一个包含当前路由动态路由参数的对象。
export async function GET(
request: Request,
{ params }: { params: Promise<{ team: string }> }
) {
const { team } = await params
}export async function GET(request, { params }) {
const { team } = await params
}| 示例 | URL | params |
|---|---|---|
app/dashboard/[team]/route.js | /dashboard/1 | Promise<{ team: '1' }> |
app/shop/[tag]/[item]/route.js | /shop/1/2 | Promise<{ tag: '1', item: '2' }> |
app/blog/[...slug]/route.js | /blog/1/2 | Promise<{ slug: ['1', '2'] }> |
Route Context 辅助函数#
您可以使用 RouteContext 为 Route Handler 的上下文添加类型,从而从路由字面量中获得强类型的 params。RouteContext 是一个全局可用的辅助函数。
import type { NextRequest } from 'next/server'
export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) {
const { id } = await ctx.params
return Response.json({ id })
}小知识
- 类型在
next dev、next build或next typegen期间生成。- 类型生成后,
RouteContext辅助函数即可全局使用。无需导入它。
示例#
Cookies#
您可以使用来自 next/headers 的 cookies 读取或设置 cookie。
import { cookies } from 'next/headers'
export async function GET(request: NextRequest) {
const cookieStore = await cookies()
const a = cookieStore.get('a')
const b = cookieStore.set('b', '1')
const c = cookieStore.delete('c')
}import { cookies } from 'next/headers'
export async function GET(request) {
const cookieStore = await cookies()
const a = cookieStore.get('a')
const b = cookieStore.set('b', '1')
const c = cookieStore.delete('c')
}或者,您可以使用 Set-Cookie 头返回一个新的 Response。
import { cookies } from 'next/headers'
export async function GET(request: Request) {
const cookieStore = await 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 = await cookies()
const token = cookieStore.get('token')
return new Response('Hello, Next.js!', {
status: 200,
headers: { 'Set-Cookie': `token=${token.value}` },
})
}您也可以使用底层 Web API 从请求中读取 cookie(NextRequest):
import { type NextRequest } from 'next/server'
export async function GET(request: NextRequest) {
const token = request.cookies.get('token')
}import { type NextRequest } from 'next/server'
export async function GET(request) {
const token = request.cookies.get('token')
}Headers#
您可以使用来自 next/headers 的 headers 读取请求头。
import { headers } from 'next/headers'
import type { NextRequest } from 'next/server'
export async function GET(request: NextRequest) {
const headersList = await headers()
const referer = headersList.get('referer')
}import { headers } from 'next/headers'
export async function GET(request) {
const headersList = await headers()
const referer = headersList.get('referer')
}这个 headers 实例是只读的。要设置请求头,您需要返回一个带有新 headers 的新 Response。
import { headers } from 'next/headers'
export async function GET(request: Request) {
const headersList = await 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 = await headers()
const referer = headersList.get('referer')
return new Response('Hello, Next.js!', {
status: 200,
headers: { referer: referer },
})
}您也可以使用底层 Web API 从请求中读取请求头(NextRequest):
import { type NextRequest } from 'next/server'
export async function GET(request: NextRequest) {
const requestHeaders = new Headers(request.headers)
}import { type NextRequest } from 'next/server'
export async function GET(request) {
const requestHeaders = new Headers(request.headers)
}重新验证缓存数据#
您可以使用 revalidate 路由片段配置来重新验证缓存数据。
export const revalidate = 60
export async function GET() {
const data = await fetch('https://api.vercel.app/blog')
const posts = await data.json()
return Response.json(posts)
}export const revalidate = 60
export async function GET() {
const data = await fetch('https://api.vercel.app/blog')
const posts = await data.json()
return Response.json(posts)
}使用缓存组件(Cache Components)#
当启用缓存组件(Cache Components)时,请使用 use cache 在单独的辅助函数中缓存数据,并使用 cacheLife 设置其重新验证间隔。从 Route Handler 中移除不受支持的 revalidate 导出。
有关示例,请参阅将 GET Route Handler 迁移到缓存组件。
重定向#
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/')
}动态路由片段#
Route Handler 可以使用动态片段(Dynamic Segments)根据动态数据创建请求处理程序。
export async function GET(
request: Request,
{ params }: { params: Promise<{ slug: string }> }
) {
const { slug } = await params // 'a'、'b' 或 'c'
}export async function GET(request, { params }) {
const { slug } = await params // 'a'、'b' 或 'c'
}| 路由 | 示例 URL | params |
|---|---|---|
app/items/[slug]/route.js | /items/a | Promise<{ slug: 'a' }> |
app/items/[slug]/route.js | /items/b | Promise<{ slug: 'b' }> |
app/items/[slug]/route.js | /items/c | Promise<{ slug: 'c' }> |
使用 generateStaticParams 进行静态生成#
您可以将 generateStaticParams 与动态 Route Handler 结合使用,在构建时为指定的参数静态生成响应,同时在请求时动态处理其他参数。
使用缓存组件(Cache Components)时,可以将 generateStaticParams 与 use cache 结合使用,为预渲染的参数和运行时参数启用数据缓存。
有关示例和详细信息,请参阅 generateStaticParams 与 Route Handler 结合使用文档。
URL 查询参数#
传递给 Route Handler 的 request 对象是一个 NextRequest 实例,其中包含一些额外的便捷方法,例如用于更轻松处理查询参数的方法。
import { type NextRequest } from 'next/server'
export function GET(request: NextRequest) {
const searchParams = request.nextUrl.searchParams
const query = searchParams.get('query')
// 对于 /api/search?query=hello,query 为 "hello"
}export function GET(request) {
const searchParams = request.nextUrl.searchParams
const query = searchParams.get('query')
// 对于 /api/search?query=hello,query 为 "hello"
}流式传输#
流式传输通常与大型语言模型(LLM)(如 OpenAI)结合使用,用于生成 AI 内容。有关 AI SDK 的更多信息,请参阅其文档。
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())
}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())
}这些抽象使用 Web API 创建流。您也可以直接使用底层 Web API。
// https://developer.mozilla.org/docs/Web/API/ReadableStream#convert_an_iterator_or_async_iterator_to_a_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 方法读取 Request 体:
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() 函数读取 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 方法为特定 Route Handler 设置 CORS 头:
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',
},
})
}小知识
- 要为多个 Route Handler 添加 CORS 头,可以使用 Proxy 或
next.config.js文件。
Webhooks#
您可以使用 Route Handler 接收来自第三方服务的 webhook:
export async function POST(request: Request) {
try {
const text = await request.text()
// 处理 webhook 负载
} 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()
// 处理 webhook 负载
} catch (error) {
return new Response(`Webhook error: ${error.message}`, {
status: 400,
})
}
return new Response('Success!', {
status: 200,
})
}值得注意的是,与使用 Pages Router 的 API Routes 不同,您无需使用 bodyParser 即可使用任何额外配置。
非 UI 响应#
您可以使用 Route Handler 返回非 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>`)
}片段配置选项#
Route Handler 使用与页面和布局相同的路由片段配置。
export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto' // deprecatedexport const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto' // deprecated更多详情请参阅 API 参考。
缓存组件(Cache Components)不支持上面显示的 dynamic、dynamicParams、revalidate、fetchCache 或 runtime 导出。有关缓存,请参阅使用缓存组件进行重新验证;有关运行时要求,请参阅迁移 runtime 配置。
版本历史#
| 版本 | 变更 |
|---|---|
v15.0.0-RC | context.params 现在是一个 promise。提供了一个 codemod |
v15.0.0-RC | GET 处理程序的默认缓存从静态更改为动态 |
v13.2.0 | 引入 Route Handler。 |