Middleware 升级指南

为了改进 Middleware 以实现全面可用性 (GA)，我们根据您的反馈，对 Middleware API（以及如何在您的应用程序中定义 Middleware）进行了一些更改。

本升级指南将帮助您了解这些更改、更改的原因以及如何将现有的 Middleware 迁移到新的 API。本指南适用于以下 Next.js 开发者：

目前使用 beta 版 Next.js Middleware 功能
选择升级到下一个 Next.js 稳定版本 (v12.2)

您可以立即开始升级您的 Middleware 用法，使用最新版本 (npm i next@latest)。

注意：本指南中描述的这些更改包含在 Next.js 12.2 中。您可以保留当前的站点结构，包括嵌套的 Middleware，直到您迁移到 12.2（或 Next.js 的 canary 构建版本）。

如果您配置了 ESLint，您需要运行 npm i eslint-config-next@latest --save-dev 来升级您的 ESLint 配置，以确保使用的版本与 Next.js 版本相同。您可能还需要重启 VSCode 以使更改生效。

在 Vercel 上使用 Next.js Middleware

如果您在 Vercel 上使用 Next.js，您现有的使用 Middleware 的部署将继续工作，您可以继续使用 Middleware 部署您的站点。当您将站点升级到下一个 Next.js 稳定版本 (v12.2) 时，您需要遵循本升级指南来更新您的 Middleware。

不再支持嵌套 Middleware

更改摘要

在你的 pages 文件夹旁边定义一个单独的 Middleware 文件
无需在文件名前加下划线前缀
可以使用自定义匹配器，通过导出的 config 对象来定义匹配的路由

解释

以前，您可以在 pages 目录下的任何级别创建 _middleware.ts 文件。Middleware 的执行基于它被创建的文件路径。

根据客户反馈，我们已将此 API 替换为单个根 Middleware，它提供了以下改进：

更快的执行速度和更低的延迟：使用嵌套 Middleware，单个请求可能会调用多个 Middleware 函数。单个 Middleware 意味着单个函数执行，这更有效率。
更低的成本：Middleware 的使用按调用次数计费。使用嵌套 Middleware，单个请求可能会调用多个 Middleware 函数，这意味着每个请求会产生多次 Middleware 费用。单个 Middleware 意味着每个请求只调用一次，更具成本效益。
Middleware 可以方便地过滤路由以外的内容：使用嵌套 Middleware，Middleware 文件位于 pages 目录中，Middleware 的执行基于请求路径。通过迁移到单个根 Middleware，您仍然可以根据请求路径执行代码，但现在您可以更方便地根据其他条件（如 cookies 或请求头的存在）执行 Middleware。
确定的执行顺序：使用嵌套 Middleware，单个请求可能匹配多个 Middleware 函数。例如，对 /dashboard/users/* 的请求将调用在 /dashboard/users/_middleware.ts 和 /dashboard/_middleware.js 中定义的 Middleware。但是，执行顺序很难推断。迁移到单个根 Middleware 可以更明确地定义执行顺序。
支持 Next.js 布局 (RFC)：迁移到单个根 Middleware 有助于支持 Next.js 中的新布局 (RFC)。

如何升级

您应该在您的应用程序中声明一个单独的 Middleware 文件，该文件应位于 pages 目录旁边，并且命名时不带 _ 前缀。您的 Middleware 文件仍然可以具有 .ts 或 .js 扩展名。

Middleware 将为应用程序中的每个路由调用，并且可以使用自定义匹配器来定义匹配过滤器。以下是一个 Middleware 的示例，它为 /about/* 和 /dashboard/:path* 触发，自定义匹配器在导出的 config 对象中定义：

middleware.ts

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  return NextResponse.rewrite(new URL('/about-2', request.url))
}
 
// Supports both a single string value or an array of matchers
export const config = {
  matcher: ['/about/:path*', '/dashboard/:path*'],
}

matcher config 也允许使用完整的正则表达式，因此支持负向先行断言或字符匹配等匹配方式。可以在此处查看一个负向先行断言的示例，以匹配除特定路径以外的所有路径：

middleware.ts

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - api (API routes)
     * - _next/static (static files)
     * - favicon.ico (favicon file)
     */
    '/((?!api|_next/static|favicon.ico).*)',
  ],
}

虽然 config 选项是首选，因为它不会在每个请求上都调用，但您也可以使用条件语句来仅在匹配特定路径时运行 Middleware。使用条件语句的一个优点是为 Middleware 的执行定义显式的顺序。以下示例展示了如何合并两个以前嵌套的 Middleware：

middleware.ts

import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/about')) {
    // This logic is only applied to /about
  }
 
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    // This logic is only applied to /dashboard
  }
}

无响应体

更改摘要

Middleware 不再能生成响应体
如果您的 Middleware 确实响应了 body，则会抛出运行时错误
迁移到使用 rewrite/redirect 重写向处理响应的页面/API

解释

为了尊重客户端和服务器端导航的差异，并帮助确保开发者不会构建不安全的 Middleware，我们正在删除在 Middleware 中发送响应体的能力。这确保 Middleware 仅用于 rewrite、redirect 或修改传入请求（例如设置 cookies）。

以下模式将不再有效：

new Response('a text value')
new Response(streamOrBuffer)
new Response(JSON.stringify(obj), { headers: 'application/json' })
NextResponse.json()

如何升级

对于使用 Middleware 进行响应（例如授权）的情况，您应该迁移到使用 rewrite/redirect 重写向显示授权错误、登录表单或 API 路由的页面。

之前

pages/_middleware.ts

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { isAuthValid } from './lib/auth'
 
export function middleware(request: NextRequest) {
  // Example function to validate auth
  if (isAuthValid(request)) {
    return NextResponse.next()
  }
 
  return NextResponse.json({ message: 'Auth required' }, { status: 401 })
}

之后

middleware.ts

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { isAuthValid } from './lib/auth'
 
export function middleware(request: NextRequest) {
  // Example function to validate auth
  if (isAuthValid(request)) {
    return NextResponse.next()
  }
 
  const loginUrl = new URL('/login', request.url)
  loginUrl.searchParams.set('from', request.nextUrl.pathname)
 
  return NextResponse.redirect(loginUrl)
}

Edge API 路由

如果您以前使用 Middleware 将标头转发到外部 API，您现在可以使用 Edge API 路由

pages/api/proxy.ts

import { type NextRequest } from 'next/server'
 
export const config = {
  runtime: 'edge',
}
 
export default async function handler(req: NextRequest) {
  const authorization = req.cookies.get('authorization')
  return fetch('https://backend-api.com/api/protected', {
    method: req.method,
    headers: {
      authorization,
    },
    redirect: 'manual',
  })
}

Cookies API 已修改

更改摘要

已添加	已删除
`cookies.set`	`cookie`
`cookies.delete`	`clearCookie`
`cookies.getWithOptions`	`cookies`

解释

根据 beta 版反馈，我们正在更改 NextRequest 和 NextResponse 中的 Cookies API，使其更符合 get/set 模型。Cookies API 扩展了 Map，包括 entries 和 values 等方法。

如何升级

NextResponse 现在有一个 cookies 实例，其中包含：

cookies.delete
cookies.set
cookies.getWithOptions

以及来自 Map 的其他扩展方法。

之前

pages/_middleware.ts

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  // create an instance of the class to access the public methods. This uses `next()`,
  // you could use `redirect()` or `rewrite()` as well
  let response = NextResponse.next()
  // get the cookies from the request
  let cookieFromRequest = request.cookies['my-cookie']
  // set the `cookie`
  response.cookie('hello', 'world')
  // set the `cookie` with options
  const cookieWithOptions = response.cookie('hello', 'world', {
    path: '/',
    maxAge: 1000 * 60 * 60 * 24 * 7,
    httpOnly: true,
    sameSite: 'strict',
    domain: 'example.com',
  })
  // clear the `cookie`
  response.clearCookie('hello')
 
  return response
}

之后

middleware.ts

export function middleware() {
  const response = new NextResponse()
 
  // set a cookie
  response.cookies.set('vercel', 'fast')
 
  // set another cookie with options
  response.cookies.set('nextjs', 'awesome', { path: '/test' })
 
  // get all the details of a cookie
  const { value, ...options } = response.cookies.getWithOptions('vercel')
  console.log(value) // => 'fast'
  console.log(options) // => { name: 'vercel', Path: '/test' }
 
  // deleting a cookie will mark it as expired
  response.cookies.delete('vercel')
 
  return response
}

新的 User-Agent 辅助工具

更改摘要

用户代理不再在请求对象上可用
我们添加了一个新的 userAgent 辅助工具，以减少 Middleware 大小 17kb

解释

为了帮助减小 Middleware 的大小，我们从请求对象中提取了用户代理，并创建了一个新的辅助工具 userAgent。

该辅助工具从 next/server 导入，允许您选择使用用户代理。该辅助工具使您可以访问与请求对象中可用的相同属性。

如何升级

从 next/server 导入 userAgent 辅助工具
解构您需要使用的属性

之前

pages/_middleware.ts

import { NextRequest, NextResponse } from 'next/server'
 
export function middleware(request: NextRequest) {
  const url = request.nextUrl
  const viewport = request.ua.device.type === 'mobile' ? 'mobile' : 'desktop'
  url.searchParams.set('viewport', viewport)
  return NextResponse.rewrite(url)
}

之后

middleware.ts

import { NextRequest, NextResponse, userAgent } from 'next/server'
 
export function middleware(request: NextRequest) {
  const url = request.nextUrl
  const { device } = userAgent(request)
  const viewport = device.type === 'mobile' ? 'mobile' : 'desktop'
  url.searchParams.set('viewport', viewport)
  return NextResponse.rewrite(url)
}

不再有页面匹配数据

更改摘要

使用 URLPattern 来检查 Middleware 是否正在为特定页面匹配调用

import { NextResponse } from 'next/server'
import type { NextRequest, NextFetchEvent } from 'next/server'
 
export function middleware(request: NextRequest, event: NextFetchEvent) {
  const { params } = event.request.page
  const { locale, slug } = params
 
  if (locale && slug) {
    const { search, protocol, host } = request.nextUrl
    const url = new URL(`${protocol}//${locale}.${host}/${slug}${search}`)
    return NextResponse.redirect(url)
  }
}

之后

middleware.ts

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
 
const PATTERNS = [
  [
    new URLPattern({ pathname: '/:locale/:slug' }),
    ({ pathname }) => pathname.groups,
  ],
]
 
const params = (url) => {
  const input = url.split('?')[0]
  let result = {}
 
  for (const [pattern, handler] of PATTERNS) {
    const patternResult = pattern.exec(input)
    if (patternResult !== null && 'pathname' in patternResult) {
      result = handler(patternResult)
      break
    }
  }
  return result
}
 
export function middleware(request: NextRequest) {
  const { locale, slug } = params(request.url)
 
  if (locale && slug) {
    const { search, protocol, host } = request.nextUrl
    const url = new URL(`${protocol}//${locale}.${host}/${slug}${search}`)
    return NextResponse.redirect(url)
  }
}

在 Next.js 内部请求上执行 Middleware

更改摘要

Middleware 将为所有请求执行，包括 _next

解释

在 Next.js v12.2 之前，Middleware 不会为 _next 请求执行。

对于 Middleware 用于授权的情况，您应该迁移到使用 rewrite/redirect 重写向显示授权错误、登录表单或 API 路由的页面。

有关如何迁移到使用 rewrite/redirect 的示例，请参阅无响应体。