跳至内容

中间件

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

中间件在匹配缓存内容和路由之前运行。有关更多详细信息,请参阅匹配路径

用例

将中间件集成到您的应用程序中可以显著提高性能、安全性以及用户体验。中间件特别有效的某些常见场景包括

  • 身份验证和授权:在授予对特定页面或 API 路由的访问权限之前,确保用户身份并检查会话 Cookie。
  • 服务器端重定向:根据某些条件(例如,语言环境、用户角色)在服务器级别重定向用户。
  • 路径重写:通过根据请求属性动态地将路径重写为 API 路由或页面,支持 A/B 测试、功能推出或旧版路径。
  • 机器人检测:通过检测和阻止机器人流量来保护您的资源。
  • 日志记录和分析:在页面或 API 处理之前,捕获和分析请求数据以获取洞察。
  • 功能标记:动态启用或禁用功能,以便无缝推出或测试功能。

认识到中间件可能不是最佳方法的情况同样至关重要。以下是一些需要注意的场景

  • 复杂的数据获取和操作:中间件并非旨在进行直接的数据获取或操作,而应在路由处理程序或服务器端实用程序中进行。
  • 繁重的计算任务:中间件应轻量级且快速响应,否则会导致页面加载延迟。繁重的计算任务或长时间运行的进程应在专用的路由处理程序中完成。
  • 广泛的会话管理:虽然中间件可以管理基本的会话任务,但广泛的会话管理应由专用身份验证服务或在路由处理程序中管理。
  • 直接数据库操作:不建议在中间件中执行直接数据库操作。数据库交互应在路由处理程序或服务器端实用程序中完成。

约定

使用项目根目录中的 middleware.ts(或 .js)文件来定义中间件。例如,与 pagesapp 相同级别,或者如果适用则在 src 内部。

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

示例

middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
// This function can be marked `async` if using `await` inside
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}
 
// See "Matching Paths" below to learn more
export const config = {
  matcher: '/about/:path*',
}

匹配路径

中间件将被调用以处理**项目中的每个路由**。鉴于此,使用匹配器来精确地定位或排除特定路由至关重要。以下是执行顺序

  1. 来自 next.config.jsheaders
  2. 来自 next.config.jsredirects
  3. 中间件(rewritesredirects 等)
  4. 来自 next.config.jsbeforeFilesrewrites
  5. 文件系统路由(public/_next/static/pages/app/ 等)
  6. 来自 next.config.jsafterFilesrewrites
  7. 动态路由(/blog/[slug]

  8. 来自 next.config.jsfallback (rewrites)

有两种方法可以定义中间件将在哪些路径上运行

  1. 自定义匹配器配置
  2. 条件语句

匹配器

matcher 允许你过滤仅在特定路径上运行的中间件。

middleware.js
export const config = {
  matcher: '/about/:path*',
}

你可以使用数组语法匹配单个路径或多个路径

middleware.js
export const config = {
  matcher: ['/about/:path*', '/dashboard/:path*'],
}

matcher 配置允许使用完整的正则表达式,因此支持诸如否定前瞻或字符匹配之类的匹配。此处可以看到一个否定前瞻的示例,用于匹配除特定路径之外的所有路径

middleware.js
export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - api (API routes)
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico, sitemap.xml, robots.txt (metadata files)
     */
    '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
}

你还可以使用 missinghas 数组(或两者的组合)绕过某些请求的中间件

middleware.js
export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - api (API routes)
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico, sitemap.xml, robots.txt (metadata files)
     */
    {
      source:
        '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },
 
    {
      source:
        '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
      has: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },
 
    {
      source:
        '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
      has: [{ type: 'header', key: 'x-present' }],
      missing: [{ type: 'header', key: 'x-missing', value: 'prefetch' }],
    },
  ],
}

注意matcher 值需要是常量,以便在构建时进行静态分析。诸如变量之类的动态值将被忽略。

配置的匹配器

  1. 必须以 / 开头
  2. 可以包含命名参数:/about/:path 匹配 /about/a/about/b,但不匹配 /about/a/c
  3. 可以在命名参数上使用修饰符(以 : 开头):/about/:path* 匹配 /about/a/b/c,因为 * 表示“零个或多个”。? 表示“零个或一个”,+ 表示“一个或多个”
  4. 可以使用括号括起来的正则表达式:/about/(.*)/about/:path* 相同

path-to-regexp 文档中阅读更多详细信息。

注意:为了向后兼容,Next.js 始终将 /public 视为 /public/index。因此,/public/:path 的匹配器将匹配。

条件语句

middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/about')) {
    return NextResponse.rewrite(new URL('/about-2', request.url))
  }
 
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.rewrite(new URL('/dashboard/user', request.url))
  }
}

NextResponse

NextResponse API 允许你

  • 将传入请求 redirect 到不同的 URL
  • 通过显示给定 URL 来 rewrite 响应
  • 为 API 路由、getServerSidePropsrewrite 目标设置请求头
  • 设置响应 Cookie
  • 设置响应头

要从中间件生成响应,你可以

  1. rewrite 到生成响应的路由(页面路由处理程序
  2. 直接返回 NextResponse。请参阅 生成响应

使用 Cookie

Cookie 是常规的 header。在 Request 中,它们存储在 Cookie header 中。在 Response 中,它们存储在 Set-Cookie header 中。Next.js 提供了一种便捷的方式,可以通过 NextRequestNextResponse 上的 cookies 扩展来访问和操作这些 Cookie。

  1. 对于传入请求,cookies 带有以下方法:getgetAllsetdelete Cookie。你可以使用 has 检查 Cookie 是否存在,或使用 clear 删除所有 Cookie。
  2. 对于传出响应,cookies 具有以下方法 getgetAllsetdelete
middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  // Assume a "Cookie:nextjs=fast" header to be present on the incoming request
  // Getting cookies from the request using the `RequestCookies` API
  let cookie = request.cookies.get('nextjs')
  console.log(cookie) // => { name: 'nextjs', value: 'fast', Path: '/' }
  const allCookies = request.cookies.getAll()
  console.log(allCookies) // => [{ name: 'nextjs', value: 'fast' }]
 
  request.cookies.has('nextjs') // => true
  request.cookies.delete('nextjs')
  request.cookies.has('nextjs') // => false
 
  // Setting cookies on the response using the `ResponseCookies` API
  const response = NextResponse.next()
  response.cookies.set('vercel', 'fast')
  response.cookies.set({
    name: 'vercel',
    value: 'fast',
    path: '/',
  })
  cookie = response.cookies.get('vercel')
  console.log(cookie) // => { name: 'vercel', value: 'fast', Path: '/' }
  // The outgoing response will have a `Set-Cookie:vercel=fast;path=/` header.
 
  return response
}

设置 Header

你可以使用 NextResponse API 设置请求和响应 header(从 Next.js v13.0.0 开始提供设置请求 header 的功能)。

middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  // Clone the request headers and set a new header `x-hello-from-middleware1`
  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-hello-from-middleware1', 'hello')
 
  // You can also set request headers in NextResponse.next
  const response = NextResponse.next({
    request: {
      // New request headers
      headers: requestHeaders,
    },
  })
 
  // Set a new response header `x-hello-from-middleware2`
  response.headers.set('x-hello-from-middleware2', 'hello')
  return response
}

注意:避免设置大型 header,因为这可能会导致 431 Request Header Fields Too Large 错误,具体取决于你的后端 Web 服务器配置。

CORS

你可以在中间件中设置 CORS header 以允许跨源请求,包括 简单预检 请求。

middleware.ts
import { NextRequest, NextResponse } from 'next/server'
 
const allowedOrigins = ['https://acme.com', 'https://my-app.org']
 
const corsOptions = {
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
}
 
export function middleware(request: NextRequest) {
  // Check the origin from the request
  const origin = request.headers.get('origin') ?? ''
  const isAllowedOrigin = allowedOrigins.includes(origin)
 
  // Handle preflighted requests
  const isPreflight = request.method === 'OPTIONS'
 
  if (isPreflight) {
    const preflightHeaders = {
      ...(isAllowedOrigin && { 'Access-Control-Allow-Origin': origin }),
      ...corsOptions,
    }
    return NextResponse.json({}, { headers: preflightHeaders })
  }
 
  // Handle simple requests
  const response = NextResponse.next()
 
  if (isAllowedOrigin) {
    response.headers.set('Access-Control-Allow-Origin', origin)
  }
 
  Object.entries(corsOptions).forEach(([key, value]) => {
    response.headers.set(key, value)
  })
 
  return response
}
 
export const config = {
  matcher: '/api/:path*',
}

注意:你可以在 路由处理程序 中为各个路由配置 CORS header。

生成响应

你可以通过返回 ResponseNextResponse 实例来直接从中间件响应。(此功能自 Next.js v13.1.0 起可用)

middleware.ts
import type { NextRequest } from 'next/server'
import { isAuthenticated } from '@lib/auth'
 
// Limit the middleware to paths starting with `/api/`
export const config = {
  matcher: '/api/:function*',
}
 
export function middleware(request: NextRequest) {
  // Call our authentication function to check the request
  if (!isAuthenticated(request)) {
    // Respond with JSON indicating an error message
    return Response.json(
      { success: false, message: 'authentication failed' },
      { status: 401 }
    )
  }
}

waitUntilNextFetchEvent

NextFetchEvent 对象扩展了原生 FetchEvent 对象,并包含 waitUntil() 方法。

waitUntil() 方法将 Promise 作为参数,并在 Promise 完成之前延长中间件的生命周期。这对于在后台执行工作很有用。

middleware.ts
import { NextResponse } from 'next/server'
import type { NextFetchEvent, NextRequest } from 'next/server'
 
export function middleware(req: NextRequest, event: NextFetchEvent) {
  event.waitUntil(
    fetch('https://my-analytics-platform.com', {
      method: 'POST',
      body: JSON.stringify({ pathname: req.nextUrl.pathname }),
    })
  )
 
  return NextResponse.next()
}

高级中间件标志

在 Next.js 的 v13.1 中,为中间件引入了两个额外的标志,skipMiddlewareUrlNormalizeskipTrailingSlashRedirect,用于处理高级用例。

skipTrailingSlashRedirect 禁用 Next.js 添加或删除尾部斜杠的重定向。这允许中间件内部进行自定义处理,以便为某些路径保留尾部斜杠,而为其他路径不保留,这可以使增量迁移更容易。

next.config.js
module.exports = {
  skipTrailingSlashRedirect: true,
}
middleware.js
const legacyPrefixes = ['/docs', '/blog']
 
export default async function middleware(req) {
  const { pathname } = req.nextUrl
 
  if (legacyPrefixes.some((prefix) => pathname.startsWith(prefix))) {
    return NextResponse.next()
  }
 
  // apply trailing slash handling
  if (
    !pathname.endsWith('/') &&
    !pathname.match(/((?!\.well-known(?:\/.*)?)(?:[^/]+\/)*[^/]+\.\w+)/)
  ) {
    return NextResponse.redirect(
      new URL(`${req.nextUrl.pathname}/`, req.nextUrl)
    )
  }
}

skipMiddlewareUrlNormalize 允许禁用 Next.js 中的 URL 规范化,以使处理直接访问和客户端转换相同。在某些高级情况下,此选项通过使用原始 URL 提供完全控制。

next.config.js
module.exports = {
  skipMiddlewareUrlNormalize: true,
}
middleware.js
export default async function middleware(req) {
  const { pathname } = req.nextUrl
 
  // GET /_next/data/build-id/hello.json
 
  console.log(pathname)
  // with the flag this now /_next/data/build-id/hello.json
  // without the flag this would be normalized to /hello
}

运行时

中间件目前仅支持与 Edge 运行时 兼容的 API。Node.js 独有的 API 不受支持

版本历史

版本更改
v13.1.0添加了高级中间件标志
v13.0.0中间件可以修改请求头、响应头并发送响应
v12.2.0中间件已稳定,请参阅 升级指南
v12.0.9在 Edge 运行时强制使用绝对 URL (PR)
v12.0.0添加中间件(Beta)