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下配置。
/** @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.com | my-proxy.com | my-proxy.com:8443, app.my-proxy.com |
*.my-proxy.com | app.my-proxy.com | my-proxy.com, app.my-proxy.com:8443 |
**.my-proxy.com | app.my-proxy.com, app.eu.my-proxy.com | my-proxy.com |
my-proxy.com:8443 | my-proxy.com:8443 | my-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。对于同时需要这两项设置的隧道:
/** @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'。
/** @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 来启用它们。
/** @type {import('next').NextConfig} */
const config = {
experimental: {
serverActions: true,
},
}
module.exports = config