Next.js Server Actions 输入校验的边界

Server Actions 让表单可以直接调用服务端函数，但“调用路径在服务端”不等于“传入参数已经可信”。真正稳妥的边界是：浏览器校验只负责尽早提示，Server Action 入口负责重新解析和校验，授权检查负责判断当前用户能否改这条数据，业务层最后才执行写入。

官方地址：https://nextjs.org/docs/app/guides/forms

我在处理一个资料编辑表单时，最容易踩的坑是把 required 和按钮禁用状态当成安全措施。它们能减少正常用户的误操作，却挡不住直接构造请求、重复提交或修改隐藏字段。下面把这条边界拆开。

先把“校验”拆成四层

可以把一次提交想成四道门：客户端格式提示、Action 参数解析、授权判断、业务副作用。前两层解决“数据长什么样”，第三层解决“谁能改什么”，第四层才解决“是否真的写入”。只要任何一层被省略，输入校验就容易变成表面约束。

在 Action 入口把 FormData 变成窄数据

不要把整个 FormData 或客户端传来的对象直接交给数据库。先逐项读取，只保留允许写入的字段，并把结果变成业务函数需要的窄结构。下面的例子故意把标题长度和状态枚举写在入口，后续代码就不必反复猜类型。

"use server";

type UpdateResult =
  | { ok: true }
  | { ok: false; message: string };

export async function updateProfile(formData: FormData): Promise {
  // FormData 的值可能不是字符串，先拒绝文件和缺失字段。
  const nicknameValue = formData.get("nickname");
  const bioValue = formData.get("bio");
  if (typeof nicknameValue !== "string" || typeof bioValue !== "string") {
    return { ok: false, message: "资料字段不完整" };
  }

  // 统一去除首尾空白，并限制长度，避免把异常大输入送入业务层。
  const nickname = nicknameValue.trim();
  const bio = bioValue.trim();
  if (nickname.length  24) {
    return { ok: false, message: "昵称长度应为 2 到 24 个字符" };
  }
  if (bio.length > 200) {
    return { ok: false, message: "简介不能超过 200 个字符" };
  }

  // 只把白名单字段传给后续函数，忽略客户端附加的 role 等字段。
  return saveProfile({ nickname, bio });
}

async function saveProfile(input: { nickname: string; bio: string }): Promise {
  // 这里再接入当前用户、资源归属和数据库事务；示例省略持久化实现。
  return { ok: true };
}

这里的重点不是某个校验库，而是“输入先收窄，再下沉”。如果项目使用 schema 库，也应该把 schema 放在这个入口或紧邻入口的位置，并把校验结果转换成前端能显示的稳定错误结构。

字段校验通过后仍要检查授权

“昵称是字符串”只能说明数据形状正确，不能说明当前用户有权修改目标资料。Next.js 的安全文档把 Server Actions 当作需要独立保护的服务端入口；不要只依靠页面上是否渲染了按钮，也不要只在 Client Component 里判断角色。

"use server";

export async function renameWorkspace(formData: FormData) {
  // 读取资源 ID 时不接受客户端传来的 ownerId 作为授权依据。
  const workspaceId = formData.get("workspaceId");
  const name = formData.get("name");
  if (typeof workspaceId !== "string" || typeof name !== "string") {
    return { ok: false, message: "参数不完整" };
  }

  // 身份来自服务端会话，资源归属也必须从服务端数据读取。
  const session = await getSession();
  if (!session?.userId) {
    return { ok: false, message: "请先登录" };
  }
  const workspace = await findWorkspace(workspaceId);
  if (!workspace || workspace.ownerId !== session.userId) {
    return { ok: false, message: "无权修改这个工作区" };
  }

  // 只有经过格式校验且属于当前用户的窄数据才能产生写入。
  return updateWorkspaceName(workspaceId, name.trim());
}

// 这些函数代表项目自己的会话、查询和写入层。
declare function getSession(): Promise;
declare function findWorkspace(id: string): Promise;
declare function updateWorkspaceName(id: string, name: string): Promise;

如果一个 Action 同时处理“创建记录”和“修改已有记录”，要分别写清资源归属规则，不要用一个宽泛的 isAdmin 布尔值替代细粒度判断。校验失败返回业务错误，数据库或依赖服务故障则交给统一异常处理。

把预期错误和真正异常分开

空昵称、名称过长、用户没有编辑权限，都是用户可以理解并修正的预期错误，适合通过 useActionState 或返回值展示。数据库连接失败、事务冲突或第三方服务不可用，则是异常，不能伪装成“表单填写错误”。这样前端提示才不会掩盖运维问题。

"use server";

export async function createProject(formData: FormData) {
  const name = formData.get("name");
  if (typeof name !== "string" || name.trim() === "") {
    // 预期错误返回稳定结构，供表单直接展示。
    return { ok: false, field: "name", message: "请输入项目名称" };
  }

  try {
    // 幂等键由调用方生成并在服务端按用户维度保存，防止重复点击重复创建。
    const requestKey = formData.get("requestKey");
    if (typeof requestKey !== "string" || requestKey.length > 80) {
      return { ok: false, field: "requestKey", message: "提交标识无效" };
    }
    return await insertProjectOnce({ name: name.trim(), requestKey });
  } catch (error) {
    // 真正异常交给日志和错误边界，不把内部细节返回给浏览器。
    console.error("createProject failed", error);
    throw new Error("项目创建暂时不可用");
  }
}

declare function insertProjectOnce(input: {
  name: string;
  requestKey: string;
}): Promise;

幂等键不是“输入校验”的全部，但它是副作用边界的重要补充：网络重试、用户连点或 hydration 前后的提交都可能让同一意图抵达多次。是否需要它，要看 Action 是否会创建订单、扣减库存或写入不可逆记录。

什么时候这条边界还不够

Server Action 适合和页面交互紧密的服务端变更，但它不是自动获得安全性的万能入口。面对高频公开提交、文件上传、长耗时任务、跨系统回调或需要独立限流审计的接口，还要补上速率限制、大小限制、审计日志、CSRF/来源策略和数据库约束；必要时把边界提升到独立 Route Handler 或后端服务。

可以用下面的清单收尾：

• 客户端校验是否只承担体验职责，而不是授权职责？
• Action 是否逐项读取并限制类型、长度、枚举和数量？
• 身份和资源归属是否在服务端重新查询？
• 是否只传递允许修改的字段，而不是合并整个对象？
• 副作用是否需要幂等键、事务、唯一约束或速率限制？
• 预期错误和系统异常是否使用不同处理路径？

最后的判断很简单：Server Action 的输入校验边界不在

相关问题

Server Action 里还需要客户端校验吗？

需要。客户端校验能更快反馈，但服务端必须重复执行关键校验，因为请求可以被直接构造或绕过浏览器。

隐藏字段能用来传递用户身份吗？

不能。隐藏字段仍由客户端控制，身份和权限应从服务端会话及资源数据推导。

所有校验都应该写在一个 Action 文件里吗？

不必。入口要负责收窄和授权，复杂规则可以下沉到独立 schema 或业务服务，但不能在下沉过程中丢失授权与副作用约束。