experimental.proxyClientMaxBodySize
配置使用 proxy 时的最大请求体大小。
当使用 proxy 时,Next.js 会自动克隆请求体并将其缓存在内存中,以支持多次读取——既在 proxy 中,也在底层的 route handler 中。为防止内存使用过多,该配置选项为缓冲的请求体设置了大小限制。
默认情况下,最大请求体大小为 10MB。如果请求体超过此限制,则只会缓冲到该上限为止,并记录一条警告,指出是哪条路由超出了限制。
选项#
字符串格式(推荐)#
使用易于阅读的字符串格式指定大小:
next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
proxyClientMaxBodySize: '1mb',
},
}
export default nextConfignext.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
proxyClientMaxBodySize: '1mb',
},
}
module.exports = nextConfig支持的单位:b、kb、mb、gb
数字格式#
或者,以字节为单位用数字指定大小:
next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
proxyClientMaxBodySize: 1048576, // 1MB,以字节为单位
},
}
export default nextConfignext.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
proxyClientMaxBodySize: 1048576, // 1MB,以字节为单位
},
}
module.exports = nextConfig行为#
当请求体超过配置的上限时:
- Next.js 只会缓冲前 N 个字节(不超过上限)
- 控制台会记录一条警告,指出超出上限的路由
- 请求将继续正常处理,但只有部分请求体可用
- 请求不会失败,也不会向客户端返回错误
如果你的应用需要处理完整的请求体,你应该:
- 提高
proxyClientMaxBodySize的上限 - 在应用逻辑中妥善处理部分请求体
示例#
proxy.ts
import { NextRequest, NextResponse } from 'next/server'
export async function proxy(request: NextRequest) {
// Next.js 会按照配置的大小上限自动缓冲请求体
// 你可以在 proxy 中读取请求体……
const body = await request.text()
// 如果请求体超出了上限,则只有部分数据可用
console.log('Body size:', body.length)
return NextResponse.next()
}app/api/upload/route.ts
import { NextRequest, NextResponse } from 'next/server'
export async function POST(request: NextRequest) {
// ……并且请求体在你的 route handler 中仍然可用
const body = await request.text()
console.log('Body in route handler:', body.length)
return NextResponse.json({ received: body.length })
}小知识#
- 此设置仅在应用中使用 proxy 时生效
- 10MB 的默认上限旨在平衡内存使用与典型用例
- 该上限按请求生效,而不是对所有并发请求全局生效
- 对于处理大文件上传的应用,请考虑相应地提高该上限