如何在NextJS的useFormState中引入静态类型检查？

问题背景 #

使用Next.js的useFormState结合服务端Action时，客户端表单提交的FormData与服务端预期的字段缺乏静态类型约束，无法在编译阶段发现字段名拼写错误、类型不匹配等问题。以下是基于TypeScript的纯静态类型解决方案：

步骤1：定义表单数据的静态类型接口 #

在服务端Action文件（actions.ts）中，明确描述服务端预期接收的表单字段结构：

"use server";

// 定义服务端预期的表单数据结构
interface ExpectedFormData {
  image: File; // 明确image字段为File类型
}

// 封装类型安全的FormData读取函数
function getFormField<T>(formData: FormData, key: keyof ExpectedFormData): T {
  const value = formData.get(key);
  // 仅做静态类型断言，无运行时验证逻辑
  return value as T;
}

export async function serverFunction(_: unknown, formData: FormData) {
  // 通过类型安全函数读取字段，确保字段名和类型匹配
  const imgFile = getFormField<File>(formData, "image");
  // ... 后续处理逻辑
}

步骤2：客户端表单关联类型约束 #

在客户端组件中，通过TypeScript的类型检查确保表单输入的name属性与服务端定义的字段完全一致：

"use client";

import { serverFunction } from "@/app/actions";
import { useFormState, useFormStatus } from "react-dom";
// 导入服务端定义的表单结构类型
import type { ExpectedFormData } from "@/app/actions";

const initialState = "";

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" aria-disabled={pending}>
      Add
    </button>
  );
}

export default function Example() {
  const [state, formAction] = useFormState(serverFunction, initialState);

  return (
    <div>
      <form action={formAction}>
        {/* name属性必须严格匹配ExpectedFormData的键，否则TypeScript会抛出编译错误 */}
        <input type="file" name="image" satisfies keyof ExpectedFormData />
        <SubmitButton />
        <pre>{JSON.stringify(state, null, 2)}</pre>
      </form>
    </div>
  );
}

关键说明 #

• 借助TypeScript的接口定义和keyof操作符，在编译阶段强制客户端表单字段与服务端预期一致，一旦字段名拼写错误或类型不匹配，会直接触发编译报错。
• 封装的getFormField函数仅做静态类型断言，不包含任何运行时验证逻辑，完全符合需求中的“非运行时验证方案”要求。
• 使用satisfies关键字可以直接约束input的name属性属于ExpectedFormData的键集合，避免手动拼写失误。

内容的提问来源于stack exchange，提问作者Max Yankov