middleware.js

middleware.js|ts 文件用于编写中间件，并在请求完成之前在服务器上运行代码。然后，根据传入的请求，您可以通过重写、重定向、修改请求或响应头或直接响应来修改响应。

中间件在渲染路由之前执行。它对于实现自定义服务器端逻辑（如身份验证、日志记录或处理重定向）特别有用。

在项目根目录中使用 middleware.ts（或 .js）文件来定义中间件。例如，与 app 或 pages 相同的级别，或者如果适用，则在 src 内部。

import { NextResponse, 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))
}
 
export const config = {
  matcher: '/about/:path*',
}

导出

中间件函数

该文件必须导出一个函数，作为默认导出或命名为 middleware。请注意，不支持来自同一文件的多個中間件。

// Example of default export
export default function middleware(request) {
  // Middleware logic
}

配置对象（可选）

可选地，可以与中间件函数一起导出一个配置对象。此对象包含匹配器以指定中间件适用的路径。

匹配器

matcher 选项允许您为中间件运行的特定路径设置目标。您可以通过多种方式指定这些路径

• 对于单个路径：直接使用字符串定义路径，例如 '/about'。
• 对于多个路径：使用数组列出多个路径，例如 matcher: ['/about', '/contact']，这会将中间件应用于 /about 和 /contact。

此外，matcher 通过正则表达式支持复杂的路径规范，例如 matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)']，从而可以精确控制要包含或排除的路径。

matcher 选项还接受一个包含以下键的对象数组

• source：用于匹配请求路径的路径或模式。它可以是用于直接路径匹配的字符串，也可以是用于更复杂匹配的模式。
• regexp（可选）：一个正则表达式字符串，根据源对匹配进行微调。它提供了对要包含或排除的路径的额外控制。
• locale（可选）：一个布尔值，当设置为 false 时，会忽略路径匹配中的基于区域设置的路由。
• has（可选）：根据特定请求元素（如标头、查询参数或 Cookie）的存在指定条件。
• missing（可选）：专注于某些请求元素不存在的条件，例如缺少标头或 Cookie。

export const config = {
  matcher: [
    {
      source: '/api/*',
      regexp: '^/api/(.*)',
      locale: false,
      has: [
        { type: 'header', key: 'Authorization', value: 'Bearer Token' },
        { type: 'query', key: 'userId', value: '123' },
      ],
      missing: [{ type: 'cookie', key: 'session', value: 'active' }],
    },
  ],
}

参数

request

在定义中间件时，默认导出的函数接受一个参数 request。此参数是 NextRequest 的实例，表示传入的 HTTP 请求。

import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  // Middleware logic goes here
}

知道这一点很有用:

• NextRequest 是一个表示 Next.js 中间件中传入 HTTP 请求的类型，而 NextResponse 是一个用于操作和发送回 HTTP 响应的类。

NextResponse

中间件可以使用 NextResponse 对象，该对象扩展了 Web 响应 API。通过返回 NextResponse 对象，您可以直接操作 cookie、设置标头、实现重定向和重写路径。

知道这一点很有用：对于重定向，您也可以使用 Response.redirect 代替 NextResponse.redirect。

运行时

中间件仅支持 Edge 运行时。无法使用 Node.js 运行时。

版本历史