Menu

middleware.js

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

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

在项目根目录使用 middleware.ts (或 .js) 文件来定义中间件。例如，与 app 或 pages 处于同一级别，或者如果适用的话，放在 src 目录内。

middleware.ts
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.js
import { NextResponse } from 'next/server'
 
// 如果在函数内使用 `await`，可以将此函数标记为 `async`
export function middleware(request) {
  return NextResponse.redirect(new URL('/home', request.url))
}
 
export const config = {
  matcher: '/about/:path*',
}

导出

中间件函数

该文件必须导出一个单独的函数，可以是默认导出，也可以命名为 middleware。请注意，不支持从同一文件导出多个中间件。

middleware.js
// 默认导出的例子
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 (可选)：根据特定请求元素 (如头部、查询参数或 cookie) 的存在指定条件。
  • missing (可选)：关注某些请求元素缺失的条件，如缺少头部或 cookie。
middleware.js
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 请求。

middleware.ts
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  // 中间件逻辑放在这里
}
middleware.js
export function middleware(request) {
  // 中间件逻辑放在这里
}

值得注意的是：

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

NextResponse

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

值得注意的是：对于重定向，你也可以使用 Response.redirect 而不是 NextResponse.redirect。

运行时

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

版本历史

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

了解更多关于中间件的信息

中间件

学习如何使用中间件在请求完成前运行代码。