middleware.js

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

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

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

import { NextResponse, 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。注意，不支持从同一文件导出多个中间件。

// 默认导出示例
export default function middleware(request) {
  // 中间件逻辑
}

配置对象（可选）

可选的，可以导出一个与中间件函数并列的配置对象。该对象包含 匹配器 (matcher)，用于指定中间件应用的路径。

匹配器 (Matcher)

matcher 选项允许您指定中间件运行的特定路径。可以通过以下方式定义路径：

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

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

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

• source：用于匹配请求路径的路径或模式。可以是直接路径匹配的字符串，或用于复杂匹配的模式。
• regexp（可选）：一个正则表达式字符串，基于 source 进一步调整匹配规则，提供对包含或排除路径的额外控制。
• locale（可选）：布尔值，设为 false 时忽略基于区域设置的路由匹配。
• has（可选）：指定基于特定请求元素（如头信息、查询参数或 cookies）存在的条件。
• missing（可选）：关注某些请求元素缺失的条件，如缺少头信息或 cookies。

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) {
  // 中间件逻辑写在这里
}

须知：

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

NextResponse

中间件可以使用 NextResponse 对象，它扩展了 Web Response API。通过返回 NextResponse 对象，您可以直接操作 cookies、设置头信息、实现重定向和重写路径。

须知：对于重定向，您也可以使用 Response.redirect 替代 NextResponse.redirect。

运行时 (Runtime)

中间件仅支持 边缘运行时 (Edge Runtime)，不支持 Node.js 运行时。

版本历史