Next.js Server Actions 请求体大小限制：配置、排查与生产实践

快速答案

• 核心结论：Next.js 14+ 默认限制 Server Actions 请求体为 1MB，超出会返回 413 错误；通过 serverActions.bodySizeLimit 可调整此限制。
• 首选检查：确认 Next.js 版本（14+ 无需启用 experimental.serverActions），检查代理服务器（如 Nginx）是否有独立的大小限制。
• 最小配置：在 next.config.js 中添加 serverActions: { bodySizeLimit: '5mb' } 即可将限制提升至 5MB。
• 适用边界：此配置仅影响 Server Actions，不适用于 API Routes 或中间件；在 Vercel 等无服务器环境中，平台限制（如 4.5MB）可能先于 Next.js 生效。
• 安全底线：始终配置 allowedOrigins 防止 CSRF，避免设置超过 10MB 的 bodySizeLimit，建议结合速率限制使用。

官方参考

• Next.js Server Actions 配置文档
• Next.js 14 版本 Server Actions 配置

它解决什么问题

当你的 Next.js 应用使用 Server Actions 处理表单提交或数据操作时，默认的 1MB 请求体限制会阻止上传较大的文件（如图片、视频、文档）或提交大量数据。典型报错为 413 Request Entity Too Large。此配置允许你调整这个限制，同时通过 allowedOrigins 提供 CSRF 保护。

适用场景包括：

• 用户头像上传（通常 2-5MB）
• 文档管理系统（PDF、Word 文件）
• 包含大量字段或 Base64 编码数据的表单提交
• 需要与 Next.js 缓存和重新验证机制深度集成的上传功能

核心配置与参数说明

所有配置均在项目根目录的 next.config.js（或 next.config.mjs）中完成。

JAVASCRIPT
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  serverActions: {
    bodySizeLimit: '5mb',          // 默认 '1mb'，支持 '500kb'、'3mb'、'10mb' 等格式
    allowedOrigins: ['my-proxy.com', '*.my-proxy.com'], // 可选，用于跨域场景
  },
};

module.exports = nextConfig;

参数详解

关键细节：

• bodySizeLimit 包括 multipart/form-data 的边界和头部开销（约 10-20KB）。设置限制时应留出余量，例如预期上传 1MB 文件时设置 '1.1mb'。
• allowedOrigins 的通配符模式（如 '*.my-proxy.com'）会降低安全性，建议仅用于开发或受控环境。

与 API Routes 对比

选择建议：对于与 UI 紧密耦合的数据操作（如表单提交），优先使用 Server Actions；对于需要独立于页面的 API 端点（如 Webhook 接收），使用 API Routes。

生产环境实践与注意事项

安全与性能

1. 内存消耗：增加 bodySizeLimit 会直接增加服务器内存消耗。每个大请求体都会完整加载到内存中，建议结合速率限制（如 Vercel 的 Rate Limiting 或自建中间件）使用。
2. DDoS 风险：过大的 bodySizeLimit 可能被恶意利用进行内存耗尽攻击。生产环境中建议不超过 10MB。
3. HTTPS 强制：始终使用 HTTPS 防止中间人攻击，特别是处理大文件时。

平台限制

• Vercel 无服务器环境：请求体大小受 Vercel 平台限制（当前为 4.5MB）。即使 Next.js 配置了更大的 bodySizeLimit，Vercel 也会在平台层拦截。
• 自托管环境：检查代理服务器（如 Nginx、Apache）的 client_max_body_size 或类似配置，确保它们与 Next.js 配置一致或更大。

大文件上传替代方案

如果文件超过 10MB 或需要流式处理，建议：

• 分片上传：将文件分成小块（如每块 1MB），通过多个 Server Actions 调用上传。
• 直接上传到存储服务：使用 AWS S3 预签名 URL 或类似方案，避免文件数据经过 Server Actions。
• 使用 API Routes：对于纯文件上传场景，API Routes 可以更灵活地处理流式数据。

常见报错与排查

413 Request Entity Too Large

报错信息：413 Request Entity Too Large 或 Body exceeded 1mb limit。

解决步骤：

1. 在 next.config.js 中增加 serverActions.bodySizeLimit 值，例如 '5mb'。
2. 检查代理服务器（Nginx 的 client_max_body_size、Apache 的 LimitRequestBody）是否有独立限制。
3. 如果使用 Vercel，确认文件大小不超过 4.5MB 的平台限制。

CSRF token mismatch or origin check failed

报错信息：CSRF token mismatch 或 Origin check failed。

解决步骤：

1. 在 next.config.js 的 serverActions.allowedOrigins 中添加允许的源域名。
2. 确保请求的 Origin 头与配置的域名匹配（包括协议和端口）。
3. 如果使用代理，确保 Host 头正确传递。

Server Actions not enabled (Next.js 13)

报错信息：Server Actions are not enabled。

解决步骤：

1. 在 next.config.js 中设置 experimental.serverActions: true。
2. 对于 Next.js 14+，此选项已默认启用，无需配置。

Body size limit exceeded for multipart uploads

报错信息：上传小文件时仍报大小限制错误。

解决步骤：

1. 确认 bodySizeLimit 设置已正确应用（重启开发服务器或重新部署）。
2. 考虑 multipart/form-data 的边界和头部开销（约 10-20KB），设置限制时留出余量。
3. 检查是否使用了代理或 CDN 层，它们可能有独立的大小限制。

常见问题 FAQ

Q: bodySizeLimit 是否适用于所有 Server Actions？

A: 是的，bodySizeLimit 全局应用于所有 Server Actions。如果需要为不同操作设置不同限制，可以考虑使用多个 Server Action 或结合 API Routes 进行细粒度控制。例如，将大文件上传逻辑移到单独的 API Route，而 Server Actions 仅处理小数据操作。

Q: 如何在不增加 bodySizeLimit 的情况下处理大文件上传？

A: 可以使用分片上传（将文件分成小块，每块不超过 1MB）或流式处理。另一种方法是使用第三方存储服务（如 AWS S3 的直接上传 URL），避免将文件数据通过 Server Actions 传递。对于图片，还可以考虑在客户端压缩后再上传。

Q: allowedOrigins 支持通配符吗？

A: 是的，allowedOrigins 支持通配符模式，例如 '*.my-proxy.com' 可以匹配所有子域名。但请注意，通配符可能降低安全性，建议仅用于开发或受控环境。生产环境中应明确列出允许的源域名。