NNext.js 中文网 GitHub

proxy.js

proxy.js 文件的 API 参考。

注意: middleware 文件约定已弃用,并已重命名为 proxy。有关更多详情,请参阅迁移到 Proxy。

proxy.js|ts 文件用于编写 Proxy,并在请求完成之前在服务端运行代码。然后,根据传入的请求,你可以通过 rewrite、redirect、修改请求头或响应头,或直接返回响应来修改响应结果。

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

小知识:

Proxy 应与渲染代码分开调用,在优化的情况下会部署到你的 CDN 以快速处理重定向/rewrite,因此不应尝试依赖共享模块或全局变量。

有关不支持的指令和缓存行为,请参阅 Proxy 限制。

要将信息从 Proxy 传递给你的应用程序,请使用请求头、Cookies、rewrite、redirect 或 URL。

在项目根目录(如果适用,也可在 src 目录内)创建一个 proxy.ts(或 .js)文件,使其与 pages 或 app 位于同一层级。

如果你自定义了 pageExtensions,例如改为 .page.ts 或 .page.js,请相应地将文件命名为 proxy.page.ts 或 proxy.page.js。

proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

// 如果在内部使用 `await`,可以将此函数标记为 `async`
export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}
proxy.js
import { NextResponse } from 'next/server'

// 如果在内部使用 `await`,可以将此函数标记为 `async`
export function proxy(request) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*',
}

导出#

Proxy 函数#

该文件必须导出单个函数,可以是默认导出,也可以是名为 proxy 的导出。请注意,不支持在同一文件中导出多个 proxy。

proxy.js
// 默认导出示例
export default function proxy(request) {
  // Proxy 逻辑
}

配置对象(可选)#

可以选择与 Proxy 函数一起导出一个配置对象。该对象包含 matcher,用于指定 Proxy 适用的路径。

Matcher#

matcher 选项允许你指定 Proxy 运行的特定路径。

如果没有 matcher,Proxy 会针对每个请求运行,包括静态文件(_next/static)、图片优化文件(_next/image)以及 public/ 文件夹中的资源。建议考虑使用否定匹配模式来排除这些路径,否则身份验证逻辑或重定向可能会无意中阻止 CSS、JS 或图片的加载。

你可以通过多种方式指定路径:

  • 单个路径:直接使用字符串定义路径,例如 '/about'。
  • 多个路径:使用数组列出多个路径,例如 matcher: ['/about', '/contact'],这会将 Proxy 同时应用于 /about 和 /contact。
proxy.js
export const config = {
  matcher: ['/about/:path*', '/dashboard/:path*'],
}

此外,matcher 选项支持使用正则表达式定义复杂的路径匹配。例如,你可以使用正则 matcher 排除某些路径:

proxy.js
export const config = {
  matcher: [
    // 排除 API 路由、静态文件、图片优化文件和 .png 文件
    '/((?!api|_next/static|_next/image|.*\\.png$).*)',
  ],
}

这使你可以精确控制要包含或排除的路径。

matcher 选项接受一个对象数组,其中包含以下键:

  • source:用于匹配请求路径的路径或模式。它可以是用于直接路径匹配的字符串,也可以是用于更复杂匹配的模式。
  • locale(可选):一个布尔值,当设置为 false 时,在路径匹配中忽略基于 locale 的路由。
  • has(可选):根据特定请求元素(例如请求头、查询参数或 Cookies)的存在情况指定条件。
  • missing(可选):关注某些请求元素缺失的条件,例如缺少请求头或 Cookies。
proxy.js
export const config = {
  matcher: [
    {
      source: '/api/:path*',
      locale: false,
      has: [
        { type: 'header', key: 'Authorization', value: 'Bearer Token' },
        { type: 'query', key: 'userId', value: '123' },
      ],
      missing: [{ type: 'cookie', key: 'session', value: 'active' }],
    },
  ],
}

source 路径模式:

  1. 必须以 / 开头
  2. 可以包含命名参数:/about/:path 匹配 /about/a 和 /about/b,但不匹配 /about/a/c
  3. 可以在命名参数(以 : 开头)上使用修饰符:/about/:path* 匹配 /about/a/b/c,因为 * 表示零个或多个。? 表示零个或一个,+ 表示一个或多个
  4. 可以使用括号括起来的正则表达式:/about/(.*) 与 /about/:path* 相同
  5. 锚定到路径的开头:/about 匹配 /about 和 /about/team,但不匹配 /blog/about

有关更多细节,请阅读 path-to-regexp 文档。

小知识:

  • matcher 的值必须是常量,以便在构建时进行静态分析。诸如变量之类的动态值将被忽略。
  • 为了向后兼容,Next.js 始终将 /public 视为 /public/index。因此,/public/:path 这样的 matcher 会匹配成功。

参数#

Next.js 使用两个参数调用 Proxy 函数,依次为 request 和 event。只声明你使用的参数即可。

request#

第一个参数是 NextRequest 的实例,表示传入的 HTTP 请求。

proxy.ts
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  // Proxy 逻辑写在这里
}
proxy.js
export function proxy(request) {
  // Proxy 逻辑写在这里
}

event#

第二个参数是 NextFetchEvent 的实例。它只暴露一个方法 waitUntil(promise),该方法使 Proxy 的调用保持活跃,直到 Promise 完成,这样日志或分析等后台工作就能在响应发送后完成。完整示例请参阅 waitUntil 与 NextFetchEvent。

proxy.ts
import type { NextFetchEvent, NextRequest } from 'next/server'

export function proxy(request: NextRequest, event: NextFetchEvent) {
  event.waitUntil(
    fetch('https://example.com/log', {
      method: 'POST',
      body: JSON.stringify({ pathname: request.nextUrl.pathname }),
    })
  )
}
proxy.js
export function proxy(request, event) {
  event.waitUntil(
    fetch('https://example.com/log', {
      method: 'POST',
      body: JSON.stringify({ pathname: request.nextUrl.pathname }),
    })
  )
}

NextProxy 类型#

如果你更喜欢简写形式,可以使用 NextProxy 类型。它会自动推断 request(NextRequest)和 event(NextFetchEvent)两者的参数类型:

proxy.ts
import type { NextProxy } from 'next/server'

export const proxy: NextProxy = (request, event) => {
  event.waitUntil(Promise.resolve())
  return Response.json({ pathname: request.nextUrl.pathname })
}

小知识:

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

NextResponse#

NextResponse API 允许你:

  • 将传入请求 redirect 到其他 URL
  • 通过显示给定 URL 来 rewrite 响应
  • 为 API 路由、getServerSideProps 和 rewrite 目标设置请求头
  • 设置响应 Cookies
  • 设置响应头

要从 Proxy 生成响应,你可以:

  1. rewrite 到一个能生成响应的路由(页面或 Route Handler)
  2. 直接返回 NextResponse。请参阅生成响应

小知识: 对于重定向,你也可以使用 Response.redirect 代替 NextResponse.redirect。

要从 Proxy 生成响应,你可以:

  1. rewrite 到一个能生成响应的路由(页面或 Edge API Route)
  2. 直接返回 NextResponse。请参阅生成响应

执行顺序#

Proxy 会针对项目中的每个路由被调用。鉴于此,使用 matcher 精确指定或排除特定路由至关重要。以下是执行顺序:

  1. 来自 next.config.js 的 headers
  2. 来自 next.config.js 的 redirects
  3. Proxy(rewrites、redirects 等)
  4. 来自 next.config.js 的 beforeFiles(rewrites)
  5. 文件系统路由(public/、_next/static/、pages/、app/ 等)
  6. 来自 next.config.js 的 afterFiles(rewrites)
  7. 动态路由(/blog/[slug])
  8. 来自 next.config.js 的 fallback(rewrites)

小知识: Server Functions 在这个链条中并不是独立的路由。它们会作为对使用它们的路由发出的 POST 请求来处理,因此排除某个路径的 Proxy matcher 也会跳过该路径上的 Server Function 调用。

对 matcher 的更改或将 Server Function 重构到其他路由,都可能在无意中使 Proxy 失去覆盖。请务必在每个 Server Function 内部验证身份验证和授权,而不要仅依赖 Proxy。有关推荐做法,请参阅数据安全指南。

运行时#

Proxy 默认使用 Node.js 运行时。runtime 配置选项在 Proxy 文件中不可用。在 Proxy 中设置 runtime 配置选项会抛出错误。

高级 Proxy 标志#

在 Next.js v13.1 中,为 proxy 引入了两个额外的标志:skipProxyUrlNormalize(原为 skipMiddlewareUrlNormalize)和 skipTrailingSlashRedirect,用于处理高级用例。

skipTrailingSlashRedirect 会禁用 Next.js 为添加或移除尾部斜杠而进行的重定向。这允许在 proxy 中进行自定义处理,使某些路径保留尾部斜杠而另一些路径不保留,从而让增量迁移更加容易。

next.config.js
module.exports = {
  skipTrailingSlashRedirect: true,
}
proxy.js
const legacyPrefixes = ['/docs', '/blog']

export default async function proxy(req) {
  const { pathname } = req.nextUrl

  if (legacyPrefixes.some((prefix) => pathname.startsWith(prefix))) {
    return NextResponse.next()
  }

  // 应用尾部斜杠处理
  if (
    !pathname.endsWith('/') &&
    !pathname.match(/((?!\.well-known(?:\/.*)?)(?:[^/]+\/)*[^/]+\.\w+)/)
  ) {
    return NextResponse.redirect(
      new URL(`${req.nextUrl.pathname}/`, req.nextUrl)
    )
  }
}

skipProxyUrlNormalize 允许禁用 Next.js 中的 URL 规范化,使直接访问和客户端导航的处理方式保持一致。在某些高级情况下,此选项通过使用原始 URL 提供完全的控制。

next.config.js
module.exports = {
  skipProxyUrlNormalize: true,
}
proxy.js
export default async function proxy(req) {
  const { pathname } = req.nextUrl

  // GET /_next/data/build-id/hello.json

  console.log(pathname)
  // 启用该标志后,这里为 /_next/data/build-id/hello.json
  // 未启用该标志时,这里会被规范化为 /hello
}

示例#

条件语句#

proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/about')) {
    return NextResponse.rewrite(new URL('/about-2', request.url))
  }

  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.rewrite(new URL('/dashboard/user', request.url))
  }
}
proxy.js
import { NextResponse } from 'next/server'

export function proxy(request) {
  if (request.nextUrl.pathname.startsWith('/about')) {
    return NextResponse.rewrite(new URL('/about-2', request.url))
  }

  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.rewrite(new URL('/dashboard/user', request.url))
  }
}

使用 Cookies#

Cookies 是普通的请求头。在 Request 上,它们存储在 Cookie 请求头中;在 Response 上,它们位于 Set-Cookie 请求头中。Next.js 通过 NextRequest 和 NextResponse 上的 cookies 扩展,提供了一种访问和操作这些 Cookies 的便捷方式。

  1. 对于传入的请求,cookies 带有以下方法:get、getAll、set 和 delete Cookies。你可以用 has 检查某个 Cookie 是否存在,或用 clear 删除所有 Cookies。
  2. 对于传出的响应,cookies 带有以下方法:get、getAll、set 和 delete。
proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  // 假设传入请求中存在 "Cookie:nextjs=fast" 请求头
  // 使用 `RequestCookies` API 从请求中获取 Cookies
  let cookie = request.cookies.get('nextjs')
  console.log(cookie) // => { name: 'nextjs', value: 'fast', Path: '/' }
  const allCookies = request.cookies.getAll()
  console.log(allCookies) // => [{ name: 'nextjs', value: 'fast' }]

  request.cookies.has('nextjs') // => true
  request.cookies.delete('nextjs')
  request.cookies.has('nextjs') // => false

  // 使用 `ResponseCookies` API 在响应上设置 Cookies
  const response = NextResponse.next()
  response.cookies.set('vercel', 'fast')
  response.cookies.set({
    name: 'vercel',
    value: 'fast',
    path: '/',
  })
  cookie = response.cookies.get('vercel')
  console.log(cookie) // => { name: 'vercel', value: 'fast', Path: '/' }
  // 传出的响应将带有 `Set-Cookie:vercel=fast;path=/` 请求头。

  return response
}
proxy.js
import { NextResponse } from 'next/server'

export function proxy(request) {
  // 假设传入请求中存在 "Cookie:nextjs=fast" 请求头
  // 使用 `RequestCookies` API 从请求中获取 Cookies
  let cookie = request.cookies.get('nextjs')
  console.log(cookie) // => { name: 'nextjs', value: 'fast', Path: '/' }
  const allCookies = request.cookies.getAll()
  console.log(allCookies) // => [{ name: 'nextjs', value: 'fast' }]

  request.cookies.has('nextjs') // => true
  request.cookies.delete('nextjs')
  request.cookies.has('nextjs') // => false

  // 使用 `ResponseCookies` API 在响应上设置 Cookies
  const response = NextResponse.next()
  response.cookies.set('vercel', 'fast')
  response.cookies.set({
    name: 'vercel',
    value: 'fast',
    path: '/',
  })
  cookie = response.cookies.get('vercel')
  console.log(cookie) // => { name: 'vercel', value: 'fast', Path: '/' }
  // 传出的响应将带有 `Set-Cookie:vercel=fast;path=/` 请求头。

  return response
}

设置请求头#

你可以使用 NextResponse API 设置请求头和响应头(设置请求头的功能从 Next.js v13.0.0 起可用)。

proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  // 克隆请求头并设置一个新的请求头 `x-hello-from-proxy1`
  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-hello-from-proxy1', 'hello')

  // 你也可以在 NextResponse.next 中设置请求头
  const response = NextResponse.next({
    request: {
      // 新的请求头
      headers: requestHeaders,
    },
  })

  // 设置一个新的响应头 `x-hello-from-proxy2`
  response.headers.set('x-hello-from-proxy2', 'hello')
  return response
}
proxy.js
import { NextResponse } from 'next/server'

export function proxy(request) {
  // 克隆请求头并设置一个新的请求头 `x-hello-from-proxy1`
  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-hello-from-proxy1', 'hello')

  // 你也可以在 NextResponse.next 中设置请求头
  const response = NextResponse.next({
    request: {
      // 新的请求头
      headers: requestHeaders,
    },
  })

  // 设置一个新的响应头 `x-hello-from-proxy2`
  response.headers.set('x-hello-from-proxy2', 'hello')
  return response
}

请注意,此代码片段使用了:

  • NextResponse.next({ request: { headers: requestHeaders } }),使 requestHeaders 对上游可用
  • 不要使用 NextResponse.next({ headers: requestHeaders }),这会使 requestHeaders 对客户端可用

有关更多信息,请参阅 Proxy 中的 NextResponse 请求头。

小知识: 避免设置过大的请求头,因为根据你的后端 Web 服务器配置,这可能会导致 431 Request Header Fields Too Large 错误。

RSC 请求与 rewrite#

在 RSC 请求期间,Next.js 会从 Proxy 中的 request 实例里剥离内部的 Flight 请求头。例如,rsc、next-router-state-tree 和 next-router-prefetch 等请求头不会通过 request.headers 暴露出来。这是为了防止意外地对 RSC 请求和与 HTML 请求采取不同的处理,因为两者需要保持一致。

当你使用 NextResponse.rewrite() 时,Next.js 会自动将所需的 RSC rewrite 请求头向上游传播。

如果你使用 fetch() 而不是 NextResponse.rewrite() 来实现自定义 rewrite 逻辑,除非手动转发这些请求头,否则可能会遇到缺失 RSC 请求头的问题。

对于自定义的 fetch rewrite 配置,你还可以在 next.config.js 中启用 skipProxyUrlNormalize,以便 rewrite 逻辑能从提供的请求对象中获得所需的 URL 形式和 RSC 请求头:

next.config.js
module.exports = {
  skipProxyUrlNormalize: true,
}

CORS#

你可以在 Proxy 中设置 CORS 请求头以允许跨域请求,包括简单请求和预检请求。

proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

const allowedOrigins = ['https://acme.com', 'https://my-app.org']

const corsOptions = {
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
}

export function proxy(request: NextRequest) {
  // 从请求中检查 origin
  const origin = request.headers.get('origin') ?? ''
  const isAllowedOrigin = allowedOrigins.includes(origin)

  // 处理预检请求
  const isPreflight = request.method === 'OPTIONS'

  if (isPreflight) {
    const preflightHeaders = {
      ...(isAllowedOrigin && { 'Access-Control-Allow-Origin': origin }),
      ...corsOptions,
    }
    return NextResponse.json({}, { headers: preflightHeaders })
  }

  // 处理简单请求
  const response = NextResponse.next()

  if (isAllowedOrigin) {
    response.headers.set('Access-Control-Allow-Origin', origin)
  }

  Object.entries(corsOptions).forEach(([key, value]) => {
    response.headers.set(key, value)
  })

  return response
}

export const config = {
  matcher: '/api/:path*',
}
proxy.js
import { NextResponse } from 'next/server'

const allowedOrigins = ['https://acme.com', 'https://my-app.org']

const corsOptions = {
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
}

export function proxy(request) {
  // 从请求中检查 origin
  const origin = request.headers.get('origin') ?? ''
  const isAllowedOrigin = allowedOrigins.includes(origin)

  // 处理预检请求
  const isPreflight = request.method === 'OPTIONS'

  if (isPreflight) {
    const preflightHeaders = {
      ...(isAllowedOrigin && { 'Access-Control-Allow-Origin': origin }),
      ...corsOptions,
    }
    return NextResponse.json({}, { headers: preflightHeaders })
  }

  // 处理简单请求
  const response = NextResponse.next()

  if (isAllowedOrigin) {
    response.headers.set('Access-Control-Allow-Origin', origin)
  }

  Object.entries(corsOptions).forEach(([key, value]) => {
    response.headers.set(key, value)
  })

  return response
}

export const config = {
  matcher: '/api/:path*',
}

小知识: 你可以在 Route Handlers 中为单个路由配置 CORS 请求头。

生成响应#

你可以通过返回 Response 或 NextResponse 实例直接从 Proxy 生成响应。(此功能从 Next.js v13.1.0 起可用)

proxy.ts
import type { NextRequest } from 'next/server'
import { isAuthenticated } from '@lib/auth'

// 将 proxy 限制在以 `/api/` 开头的路径
export const config = {
  matcher: '/api/:function*',
}

export function proxy(request: NextRequest) {
  // 调用身份验证函数来检查请求
  if (!isAuthenticated(request)) {
    // 返回带有错误消息的 JSON 响应
    return Response.json(
      { success: false, message: 'authentication failed' },
      { status: 401 }
    )
  }
}
proxy.js
import { isAuthenticated } from '@lib/auth'

// 将 proxy 限制在以 `/api/` 开头的路径
export const config = {
  matcher: '/api/:function*',
}

export function proxy(request) {
  // 调用身份验证函数来检查请求
  if (!isAuthenticated(request)) {
    // 返回带有错误消息的 JSON 响应
    return Response.json(
      { success: false, message: 'authentication failed' },
      { status: 401 }
    )
  }
}

否定匹配#

matcher 配置支持完整的正则表达式,因此支持负向前瞻或字符匹配等匹配方式。下面是一个使用负向前瞻匹配除特定路径之外所有路径的示例:

proxy.js
export const config = {
  matcher: [
    /*
     * 匹配所有请求路径,但以下列内容开头的路径除外:
     * - api(API 路由)
     * - _next/static(静态文件)
     * - _next/image(图片优化文件)
     * - favicon.ico、sitemap.xml、robots.txt(元数据文件)
     */
    '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
}

你还可以通过使用 missing 或 has 数组,或两者结合,来为某些请求绕过 Proxy:

proxy.js
export const config = {
  matcher: [
    /*
     * 匹配所有请求路径,但以下列内容开头的路径除外:
     * - api(API 路由)
     * - _next/static(静态文件)
     * - _next/image(图片优化文件)
     * - favicon.ico、sitemap.xml、robots.txt(元数据文件)
     */
    {
      source:
        '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },

    {
      source:
        '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
      has: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' },
      ],
    },

    {
      source:
        '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
      has: [{ type: 'header', key: 'x-present' }],
      missing: [{ type: 'header', key: 'x-missing', value: 'prefetch' }],
    },
  ],
}

小知识:

即使 _next/data 在否定 matcher 模式中被排除,proxy 仍会针对 _next/data 路由被调用。这是有意的行为,用于防止出现这样的安全问题:你保护了某个页面,却忘记保护相应的数据路由。

proxy.js
export const config = {
  matcher:
    '/((?!api|_next/data|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
}

// 尽管已被排除,Proxy 仍会针对 /_next/data/* 路由运行

waitUntil 与 NextFetchEvent#

NextFetchEvent 对象扩展了原生 FetchEvent 对象,并包含 waitUntil() 方法。

waitUntil() 方法接受一个 Promise 作为参数,并延长 Proxy 的生命周期,直到该 Promise 完成。这对于在后台执行工作非常有用。

proxy.ts
import { NextResponse } from 'next/server'
import type { NextFetchEvent, NextRequest } from 'next/server'

export function proxy(req: NextRequest, event: NextFetchEvent) {
  event.waitUntil(
    fetch('https://my-analytics-platform.com', {
      method: 'POST',
      body: JSON.stringify({ pathname: req.nextUrl.pathname }),
    })
  )

  return NextResponse.next()
}

单元测试(实验性)#

从 Next.js 15.1 开始,next/experimental/testing/server 包中包含一些实用工具,可帮助对 proxy 文件进行单元测试。对 proxy 进行单元测试有助于确保它只在期望的路径上运行,并确保自定义路由逻辑在代码进入生产环境之前按预期工作。

unstable_doesMiddlewareMatch 函数可用于断言 proxy 是否会针对提供的 URL、请求头和 Cookies 运行。

js
import { unstable_doesMiddlewareMatch } from 'next/experimental/testing/server'

expect(
  unstable_doesMiddlewareMatch({
    config,
    nextConfig,
    url: '/test',
  })
).toEqual(false)

也可以测试整个 proxy 函数。

js
import { isRewrite, getRewrittenUrl } from 'next/experimental/testing/server'

const request = new NextRequest('https://nextjs.org/docs')
const response = await proxy(request)
expect(isRewrite(response)).toEqual(true)
expect(getRewrittenUrl(response)).toEqual('https://other-domain.com/docs')
// 如果响应是 redirect,也可以使用 getRedirectUrl

平台支持#

部署选项是否支持
Node.js 服务器是
Docker 容器是
静态导出否
Adapters取决于平台

了解在自托管 Next.js 时如何配置 Proxy。

迁移到 Proxy#

为何做出此更改#

将 middleware 重命名的原因是,"middleware"一词常常与 Express.js 的 middleware 混淆,导致对其用途产生误解。此外,Middleware 功能非常强大,这可能会鼓励人们使用它;不过,建议将此功能作为最后的手段。

Next.js 正致力于提供更好用、更符合人体工程学的 API,使开发者无需使用 Middleware 也能实现目标。这就是将 middleware 重命名的原因。

为何叫 "Proxy"#

Proxy 这个名称明确了 Middleware 的能力。"proxy"一词暗示了位于应用之前的网络边界,这也正是该功能的行为方式。它可以在应用程序的主运行时之外运行,并在请求到达你的应用之前对其进行处理。这些特性与"proxy"一词更加契合,也让该功能的用途更加清晰。

如何迁移#

我们建议用户避免依赖 Middleware,除非没有其他选择。我们的目标是提供更好用的 API,让用户无需 Middleware 也能实现目标。

"middleware"一词常常使用户联想到 Express.js 的 middleware,这可能导致误用。为明确我们的方向,我们正在将文件约定重命名为"proxy"。这凸显了我们正在逐步远离 Middleware,拆分其过载的功能,并让 Proxy 的用途更加清晰。

Next.js 提供了一个 codemod,用于将 middleware.ts 迁移到 proxy.ts。你可以运行以下命令进行迁移:

bash
npx @next/codemod@canary middleware-to-proxy .

该 codemod 会将文件名和函数名从 middleware 重命名为 proxy。

diff
// middleware.ts -> proxy.ts

- export function middleware() {
+ export function proxy() {

版本历史#

版本变更
v16.0.0Middleware 已弃用并更名为 Proxy。Proxy 默认使用 Node.js 运行时
v15.5.0Middleware 现在可以使用 Node.js 运行时(稳定版)
v15.2.0Middleware 现在可以使用 Node.js 运行时(实验性)
v13.1.0新增高级 Middleware 标志
v13.0.0Middleware 可以修改请求头、响应头并发送响应
v12.2.0Middleware 已稳定,请参阅升级指南
v12.0.9在 Edge Runtime 中强制使用绝对 URL(PR)
v12.0.0新增 Middleware(Beta)
Next.js 中文网