如何在 React Router v6 中使用 Form 组件正确提交文件数据

本文详解 React Router DOM 的 组件如何通过设置 encType="multipart/form-data" 实现多文件上传，解决因表单编码类型缺失导致后端无法解析 File 对象的问题，并提供完整可运行的前后端协同示例。

本文详解 react router dom 的 `

<Form method="post" encType="multipart/form-data">
  <div>
    <label htmlFor="tradeLicensePhoto">Copy of trade license</label>
    <input
      id="tradeLicensePhoto"
      type="file"
      name="tradeLicensePhoto"
      accept="image/*"
      required
    />
  </div>
  <div>
    <label htmlFor="profilePhoto">Profile Photo</label>
    <input
      id="profilePhoto"
      type="file"
      name="profilePhoto"
      accept="image/*"
      required
    />
  </div>
  {/* 其他文件输入字段... */}
  <button type="submit">
    {isSubmitting ? "Submitting..." : "Save"}
  </button>
</Form>

? Action 端：正确处理 FormData

request.formData() 返回的是 FormData 实例，其 .get() 方法返回的是 File 对象（非字符串），不能直接 JSON.stringify()。否则会得到 "[object File]"，且服务端无法解析。

创客贴设计

创客贴设计，一款智能在线设计工具，设计不求人，AI助你零基础完成专业设计！

下载

✅ 正确的 action 实现应使用 FormData 直接提交，或转换为 multipart/form-data 格式：

export async function authenticationAction({ request }: ActionArgs) {
  const formData = await request.formData();

  // ✅ 推荐：直接转发 FormData（保持文件二进制完整性）
  const response = await fetch("https://your-api.com/upload", {
    method: "POST",
    body: formData, // 不要加 headers —— 浏览器会自动设置正确的 Content-Type 和 boundary
  });

  if (!response.ok) {
    const errorData = await response.json();
    throw json({ message: errorData.message || "Upload failed" }, { status: response.status });
  }

  return json({ success: true, message: "Files uploaded successfully" });
}

❌ 错误示例（即原文问题）：

// ❌ 错误：将 File 对象转为 JSON 会丢失二进制数据
const authData = {
  profilePhoto: data.get("profilePhoto"), // → File 对象，JSON.stringify 后变成 "[object File]"
};
body: JSON.stringify(authData) // → 后端收不到真实文件！

? 补充注意事项

• 服务端要求：确保后端 API 支持 multipart/form-data 解析（如 Express 需 multer，Next.js 可用 next-connect + multer，Cloudflare Workers 需手动解析 formData()）。
• 文件校验建议：在 action 中可先校验文件是否存在、类型/大小是否合规：

  const profilePhoto = formData.get("profilePhoto") as File | null;
  if (!profilePhoto || profilePhoto.size === 0) {
    throw json({ message: "Profile photo is required" }, { status: 400 });
  }

• 客户端体验优化：可结合 useNavigation() 获取提交状态，或使用 fetcher 实现无刷新上传。

✅ 总结

遵循以上规范，即可在 React Router 的声明式路由体系中稳定、安全地完成多文件上传任务。