路由处理程序
路由处理程序允许你使用 Web 的 Request 和 Response API 为给定路由创建自定义请求处理程序。
值得注意的是: 路由处理程序仅在 app
目录中可用。它们相当于 pages
目录中的 API 路由,这意味着你不需要同时使用 API 路由和路由处理程序。
路由处理程序在 app
目录中的 route.js|ts
文件中定义:
路由处理程序可以嵌套在 app
目录的任何位置,类似于 page.js
和 layout.js
。但是在同一路由段级别上不能同时存在 route.js
文件和 page.js
文件。
支持以下 HTTP 方法: GET
、POST
、PUT
、PATCH
、DELETE
、HEAD
和 OPTIONS
。如果调用了不支持的方法,Next.js 将返回 405 Method Not Allowed
响应。
除了支持原生的 Request 和 Response API 外,Next.js 还通过 NextRequest
和 NextResponse
对它们进行了扩展,为高级用例提供了便捷的辅助函数。
路由处理程序默认不会被缓存。但是,你可以为 GET
方法选择启用缓存。要做到这一点,可以在路由处理程序文件中使用 路由配置选项,比如 export const dynamic = 'force-static'
。
像 sitemap.ts
、opengraph-image.tsx
和 icon.tsx
这样的特殊路由处理程序,以及其他 元数据文件 默认情况下仍然是静态的,除非它们使用动态函数或动态配置选项。
你可以将 route
视为最低级别的路由原语。
- 它们不参与布局或客户端导航,不像
page
。
- 在同一路由上不能同时存在
route.js
文件和 page.js
文件。
页面 | 路由 | 结果 |
---|
app/page.js | app/route.js | 冲突 |
app/page.js | app/api/route.js | 有效 |
app/[user]/page.js | app/api/route.js | 有效 |
每个 route.js
或 page.js
文件都会接管该路由的所有 HTTP 动词。
以下示例展示了如何将路由处理程序与其他 Next.js API 和功能结合使用。
你可以使用 next.revalidate
选项 重新验证缓存数据:
或者,你可以使用 revalidate
段配置选项:
路由处理程序可以与 Next.js 的动态函数一起使用,比如 cookies
和 headers
。
你可以使用 next/headers
中的 cookies
读取或设置 cookies。这个服务器函数可以直接在路由处理程序中调用,也可以嵌套在另一个函数中。
或者,你可以使用 Set-Cookie
头部返回一个新的 Response
。
你也可以使用底层的 Web API 从请求 (NextRequest
) 中读取 cookies:
你可以使用 next/headers
中的 headers
读取 headers。这个服务器函数可以直接在路由处理程序中调用,也可以嵌套在另一个函数中。
这个 headers
实例是只读的。要设置 headers,你需要返回一个带有新 headers
的新 Response
。
你也可以使用底层的 Web API 从请求 (NextRequest
) 中读取 headers:
我们建议在继续之前先阅读 定义路由 页面。
路由处理程序可以使用 动态段 来创建基于动态数据的请求处理程序。
路由 | 示例 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' } |
传递给路由处理程序的请求对象是 NextRequest
实例,它有 一些额外的便利方法,包括更容易处理查询参数。
流式传输通常与大语言模型 (LLMs) 结合使用,例如 OpenAI,用于 AI 生成的内容。了解更多关于 AI SDK 的信息。
这些抽象使用了 Web API 来创建流。你也可以直接使用底层的 Web API。
你可以使用标准的 Web API 方法读取 Request
体:
你可以使用 request.formData()
函数读取 FormData
:
由于 formData
数据都是字符串,你可能想使用 zod-form-data
来验证请求并以你喜欢的格式(例如 number
)检索数据。
你可以使用标准的 Web API 方法为特定的路由处理程序设置 CORS 头:
值得注意的是:
你可以使用路由处理程序来接收来自第三方服务的 webhooks:
值得注意的是,与页面路由器中的 API 路由不同,你不需要使用 bodyParser
或任何额外的配置。
你可以使用路由处理程序返回非 UI 内容。注意,sitemap.xml
、robots.txt
、app icons
和 open graph 图片 都有内置支持。
路由处理程序使用与页面和布局相同的 路由段配置。
查看 API 参考 了解更多详情。