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 Response API。通过返回 NextResponse 对象，你可以直接操作 Cookie、设置标头、实现重定向和重写路径。

须知：对于重定向，你还可以使用 Response.redirect 而不是 NextResponse.redirect。

运行时

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

版本历史