Next.js 中文网

主题

proxyClientMaxBodySize ​

使用代理时，Next.js 会自动克隆请求体并将其缓冲在内存中，以支持多次读取。 - 在代理和底层路由处理程序中均可添加。为防止内存使用过多，此配置选项设置了缓冲正文的大小限制。

¥When proxy is used, Next.js automatically clones the request body and buffers it in memory to enable multiple reads - both in proxy and the underlying route handler. To prevent excessive memory usage, this configuration option sets a size limit on the buffered body.

默认情况下，请求体大小上限为 10MB。如果请求体超过此限制，则请求体将仅缓存到限制大小，并记录一条警告，指出哪个路由超过了限制。

¥By default, the maximum body size is 10MB. If a request body exceeds this limit, the body will only be buffered up to the limit, and a warning will be logged indicating which route exceeded the limit.

选项 ​

¥Options

¥String format (recommended)

使用易于理解的字符串格式指定大小：

¥Specify the size using a human-readable string format:

ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    proxyClientMaxBodySize: '1mb',
  },
}

export default nextConfig

支持的单位：b, kb, mb, gb

¥Supported units: b, kb, mb, gb

数字格式 ​

¥Number format

或者，你可以将大小（以字节为单位）指定为数字：

¥Alternatively, specify the size in bytes as a number:

ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    proxyClientMaxBodySize: 1048576, // 1MB in bytes
  },
}

export default nextConfig

行为 ​

¥Behavior

当请求体超过配置的限制时：

¥When a request body exceeds the configured limit:

  1. Next.js 只会缓存前 N 个字节（最多不超过限制）。

    ¥Next.js will buffer only the first N bytes (up to the limit)

  2. 控制台将记录一条警告，指示超出限制的路由。

    ¥A warning will be logged to the console indicating the route that exceeded the limit

  3. 请求将继续正常处理，但只有部分响应体可用。

    ¥The request will continue processing normally, but only the partial body will be available

  4. 请求不会失败，也不会向客户端返回错误。

    ¥The request will not fail or return an error to the client

如果你的应用需要处理完整的请求体，则应执行以下操作之一：

¥If your application needs to process the full request body, you should either:

  • 增加 proxyClientMaxBodySize 限制

    ¥Increase the proxyClientMaxBodySize limit

  • 在应用逻辑中优雅地处理部分请求体

    ¥Handle the partial body gracefully in your application logic

示例 ​

¥Example

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

export async function proxy(request: NextRequest) {
  // Next.js automatically buffers the body with the configured size limit
  // You can read the body in proxy...
  const body = await request.text()

  // If the body exceeded the limit, only partial data will be available
  console.log('Body size:', body.length)

  return NextResponse.next()
}
ts
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  // ...and the body is still available in your route handler
  const body = await request.text()

  console.log('Body in route handler:', body.length)

  return NextResponse.json({ received: body.length })
}

很高兴知道 ​

¥Good to know

  • 此设置仅在你的应用中使用代理时生效

    ¥This setting only applies when proxy is used in your application

  • 10MB 的默认限制旨在平衡内存使用和典型使用场景。

    ¥The default limit of 10MB is designed to balance memory usage and typical use cases

  • 此限制适用于每个请求，而非所有并发请求的全局限制。

    ¥The limit applies per-request, not globally across all concurrent requests

  • 对于处理大型文件上传的应用，请考虑相应地增加限制。

    ¥For applications handling large file uploads, consider increasing the limit accordingly