Next.js 中文网

主题

代理 ​

¥Proxy

代理 ​

¥Proxy

需要了解：从 Next.js 16 开始，中间件现在更名为代理，以更好地体现其用途。功能保持不变。

¥Good to know: Starting with Next.js 16, Middleware is now called Proxy to better reflect its purpose. The functionality remains the same.

代理允许你在请求完成之前运行代码。然后，根据传入的请求，你可以通过重写、重定向、修改请求或响应标头或直接响应来修改响应。

¥Proxy allows you to run code before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly.

用例 ​

¥Use cases

代理有效的常见场景包括：

¥Some common scenarios where Proxy is effective include:

  • 修改所有页面或部分页面的标题

    ¥Modifying headers for all pages or a subset of pages

  • 根据 A/B 测试或实验重写到不同的页面

    ¥Rewriting to different pages based on A/B tests or experiments

  • 基于传入请求属性的程序化重定向

    ¥Programmatic redirects based on incoming request properties

对于简单的重定向，请考虑首先在 next.config.ts 中使用 redirects 配置。当你需要访问请求数据或更复杂的逻辑时，应使用代理。

¥For simple redirects, consider using the redirects configuration in next.config.ts first. Proxy should be used when you need access to request data or more complex logic.

代理不适用于缓慢的数据获取。虽然代理对于 乐观检查 的某些功能（例如基于权限的重定向）很有帮助，但它不应被用作完整的会话管理或授权解决方案。

¥Proxy is not intended for slow data fetching. While Proxy can be helpful for optimistic checks such as permission-based redirects, it should not be used as a full session management or authorization solution.

在代理中使用 options.cache、options.next.revalidate 或 options.next.tags 执行 fetch 操作无效。

¥Using fetch with options.cache, options.next.revalidate, or options.next.tags, has no effect in Proxy.

惯例 ​

¥Convention

在项目根目录下创建 proxy.ts（或 .js）文件，或者如果适用，在 src 中创建，使其与 pages 或 app 位于同一级别。

¥Create a proxy.ts (or .js) file in the project root, or inside src if applicable, so that it is located at the same level as pages or app.

注意：虽然每个项目只支持一个 proxy.ts 文件，但你仍然可以将代理逻辑组织成模块。将代理功能拆分到单独的 .ts 或 .js 文件中，然后将其导入到你的主 proxy.ts 文件中。这使得路由特定的代理管理更加清晰，并聚合到 proxy.ts 中以实现集中控制。通过强制使用单个代理文件，可以简化配置、防止潜在冲突，并通过避免多个代理层来优化性能。

¥Note: While only one proxy.ts file is supported per project, you can still organize your proxy logic into modules. Break out proxy functionalities into separate .ts or .js files and import them into your main proxy.ts file. This allows for cleaner management of route-specific proxy, aggregated in the proxy.ts for centralized control. By enforcing a single proxy file, it simplifies configuration, prevents potential conflicts, and optimizes performance by avoiding multiple proxy layers.

示例 ​

¥Example

你可以将代理函数导出为默认导出或命名的 proxy 导出：

¥You can export your proxy function as either a default export or a named proxy export:

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

// This function can be marked `async` if using `await` inside
export function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}

// Alternatively, you can use a default export:
// export default function proxy(request: NextRequest) { ... }

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

matcher 配置允许你筛选代理，使其在特定路径上运行。请参阅 匹配器 文档以了解有关路径匹配的更多详细信息。

¥The matcher config allows you to filter Proxy to run on specific paths. See the Matcher documentation for more details on path matching.

了解更多关于 使用 proxy 的信息，或参考 proxy API 参考。

¥Read more about using proxy, or refer to the proxy API reference.