跳到主要内容

路由处理器和中间件

路由处理器​

路由处理器允许你使用 Web Request 和 Response API 为给定路由创建自定义请求处理器。

Route.js 特殊文件Route.js 特殊文件

提示： 路由处理器仅在 app 目录内可用。它们等同于 pages 目录内的 API 路由，这意味着你不需要同时使用 API 路由和路由处理器。

约定​

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

app/api/route.ts
export async function GET(request: Request) {}

路由处理器可以嵌套在 app 目录内的任何地方，类似于 page.js 和 layout.js。但在同一路由段级别不能有与 page.js 相同的 route.js 文件。

支持的 HTTP 方法​

支持以下 HTTP 方法：GET、POST、PUT、PATCH、DELETE、HEAD 和 OPTIONS。如果调用不支持的方法，Next.js 将返回 405 Method Not Allowed 响应。

扩展的 NextRequest 和 NextResponse API​

除了支持原生 Request 和 Response API 外，Next.js 还用 NextRequest 和 NextResponse 扩展它们，为高级用例提供便捷的辅助函数。

缓存​

路由处理器默认不会被缓存。但是，你可以选择缓存 GET 方法。其他支持的 HTTP 方法不会被缓存。要缓存 GET 方法，在路由处理器文件中使用路由配置选项，例如 export const dynamic = 'force-static'。

app/items/route.ts
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 })
}

提示： 其他支持的 HTTP 方法不会被缓存，即使它们与同一文件中的缓存 GET 方法放在一起。

特殊路由处理器​

特殊路由处理器如 sitemap.ts、opengraph-image.tsx 和 icon.tsx，以及其他元数据文件默认保持静态，除非它们使用动态 API 或动态配置选项。

路由解析​

你可以将 route 视为最低级别的路由原语。

  • 它们不参与像 page 那样的布局或客户端导航。
  • 在同一路由不能有与 page.js 相同的 route.js 文件。
页面路由结果
app/page.jsapp/route.js❌ 冲突
app/page.jsapp/api/route.js✅ 有效
app/[user]/page.jsapp/api/route.js✅ 有效

每个 route.js 或 page.js 文件接管该路由的所有 HTTP 请求方法。

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

// ❌ 冲突
// `app/route.ts`
export async function POST(request: Request) {}

了解更多关于路由处理器如何补充你的前端应用程序，或探索路由处理器 API 参考。

中间件​

中间件允许你在请求完成之前运行代码。然后，根据传入的请求，你可以通过重写、重定向、修改请求或响应头，或直接响应来修改响应。

使用场景​

中间件有效的一些常见场景包括：

  • 在读取传入请求的部分内容后进行快速重定向
  • 基于 A/B 测试或实验重写到不同页面
  • 为所有页面或页面子集修改头信息

中间件不适合：

  • 慢速数据获取
  • 会话管理

在中间件中使用带有 options.cache、options.next.revalidate 或 options.next.tags 的 fetch 没有效果。

约定​

使用项目根目录中的 middleware.ts（或 .js）文件来定义中间件。例如，与 pages 或 app 同级，或在适用的情况下在 src 内。

注意： 虽然每个项目只支持一个 middleware.ts 文件，但你仍然可以将中间件逻辑组织到模块中。将中间件功能分解为单独的 .ts 或 .js 文件，并将它们导入到主 middleware.ts 文件中。这允许更清晰地管理特定路由的中间件，在 middleware.ts 中聚合以进行集中控制。通过强制使用单个中间件文件，它简化了配置，防止潜在冲突，并通过避免多个中间件层来优化性能。

示例​

middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

// 如果内部使用 `await`，此函数可以标记为 `async`
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

// 请参阅下面的"匹配路径"了解更多信息
export const config = {
  matcher: '/about/:path*',
}

了解更多关于使用 middleware，或参考 middleware API 参考。

最后于 更新