NNext.js 中文网 GitHub

serverActions

在你的 Next.js 应用中配置 Server Actions 的行为。

用于配置 Next.js 应用中 Server Actions 行为的选项。要了解 Server Actions 的工作方式(包括这些选项所调整的安全边界),请参阅 Server Actions 指南。

allowedOrigins#

experimental.serverActions.allowedOrigins 是一个额外可信主机的列表,Server Actions 可以从这些主机调用。

为防止跨站请求伪造(CSRF),Next.js 会将请求的 Origin 头中的主机与 x-forwarded-host 进行比较,若没有 x-forwarded-host 则与 host 比较。如果不匹配,则拒绝请求,除非来源主机与 allowedOrigins 中的某个条目匹配。没有 Origin 头的请求会绕过此比较。

小知识:Server Actions 在 Next.js 14 及更高版本中已稳定并默认启用。allowedOrigins 和 bodySizeLimit 选项仍为实验性,必须在 experimental.serverActions 下配置。

next.config.js
/** @type {import('next').NextConfig} */

module.exports = {
  experimental: {
    serverActions: {
      allowedOrigins: ['my-proxy.com', '*.my-proxy.com'],
    },
  },
}

主机匹配#

只有请求的 Origin 头中的 host 会与你的条目匹配,即主机名加上 URL 携带的端口(如果有)。对于来自 https://my-proxy.com/checkout 的请求,该值为 my-proxy.com。对于来自 https://my-proxy.com:8443/checkout 的请求,则为 my-proxy.com:8443。请以相同方式编写你的条目。

条目还可以通过两种通配符扩展:* 代表主机名中的恰好一个标签,** 代表一个或多个。这就是上面示例列出两个条目的原因:一个用于裸主机,一个用于其子域名。

条目匹配不匹配
my-proxy.commy-proxy.commy-proxy.com:8443, app.my-proxy.com
*.my-proxy.comapp.my-proxy.commy-proxy.com, app.my-proxy.com:8443
**.my-proxy.comapp.my-proxy.com, app.eu.my-proxy.commy-proxy.com
my-proxy.com:8443my-proxy.com:8443my-proxy.com

不支持部分替换。请写 *.my-proxy.com,而不是 app-*.my-proxy.com。** 仅支持在模式开头使用。端口不能使用通配符,因此请完整写出:my-proxy.com:8443,或其子域名使用 *.my-proxy.com:8443。

反向代理和开发隧道#

在反向代理后面,只要代理在 x-forwarded-host 中转发公共主机,就无需添加条目。当代理改为转发自身主机时,浏览器发送的是 my-proxy.com,而服务端报告的却是类似 localhost:3000 的值,这种不匹配正是此列表的用途:应添加浏览器地址栏中可见的主机,而非服务端报告的内部主机。

该检查在生产环境和开发环境中都会运行,因此此列表适用于你已部署的应用,而不仅限于本地开发。

顶层 allowedDevOrigins 选项单独控制对开发服务器资源和端点的访问。如果这些资源的访问被阻止,请在该选项中添加隧道主机名。如果 Server Actions 未通过主机比较,请将其添加到 experimental.serverActions.allowedOrigins。对于同时需要这两项设置的隧道:

next.config.js
/** @type {import('next').NextConfig} */

module.exports = {
  allowedDevOrigins: ['*.tunnel.example.com'],
  experimental: {
    serverActions: {
      allowedOrigins: ['*.tunnel.example.com'],
    },
  },
}

bodySizeLimit#

默认情况下,发送到 Server Action 的请求体最大为 1MB,以防止解析大量数据时消耗过多服务端资源,以及潜在的 DDoS 攻击。

不过,你可以使用 experimental.serverActions.bodySizeLimit 选项配置此限制。它可以是字节数,或 bytes 支持的任何字符串格式,例如 1000、'500kb' 或 '3mb'。

next.config.js
/** @type {import('next').NextConfig} */

module.exports = {
  experimental: {
    serverActions: {
      bodySizeLimit: '2mb',
    },
  },
}

该限制适用于原始 HTTP 请求体,包括 multipart/form-data 为边界、分段头和字段元数据增加的字节。如果你预计上传大小接近配置值,请为此开销留出一些余量。对于典型的分段上传,额外 10–20 KB 是合理的经验法则。

启用 Server Actions(v13)#

Server Actions 在 Next.js 14 中成为稳定特性,并默认启用。不过,如果你使用的是更早版本的 Next.js,可以通过将 experimental.serverActions 设为 true 来启用它们。

next.config.js
/** @type {import('next').NextConfig} */
const config = {
  experimental: {
    serverActions: true,
  },
}

module.exports = config
Next.js 中文网