# React Hook 表单 + Zod 验证 **状态**：生产就绪 ✅ **最后验证**：2026-01-20 **最新版本**：react-hook-form@7.71.1、zod@4.3.5、@hookform/resolvers@5.2.2 ** ** ## 快速入门 npm安装react-hook-form@7.70.0 zod@4.3.5 @hookform/resolvers@5.2.2 **基本表格模式**： const 架构 = z.object({ 电子邮件：z.string().email(), 密码：z.string().min(8), }) // zodResolver 推断类型 — useForm 上不需要 z.infer 常量形式 = useForm({ 解析器：zodResolver（架构）， defaultValues: { email: '', password: '' }, // 需要防止出现不受控制的警告 }) const onSubmit = form.handleSubmit((value) => { 控制台.log(值) }) <表单onSubmit={onSubmit}> {form.formState.errors.email && {form.formState.errors.email.message}} **服务器验证**（关键 - 切勿跳过）： // 服务器上的相同架构 const data = schema.parse(await req.json()) ** ** ## 关键模式 **useForm 选项**（验证模式）： * `mode: 'onSubmit'`（默认）- 最佳性能 * `mode: 'onBlur'` \- 良好的平衡 * `mode: 'onChange'` \- 实时反馈，更多重新渲染 * `shouldUnregister: true` \- 卸载时删除字段数据（用于多步骤表单） **Zod 改进**（跨领域验证）： z.object({ 密码: z.string(), 确认: z.string() }) .refine((data) => data.password === data.confirm, { 消息：“密码不匹配”， path: ['confirm'], // CRITICAL: 此字段出现错误 }) **佐德变换**： z.string().transform((val) => val.toLowerCase()) // 数据操作 z.string().transform(parseInt).refine((v) => v > 0) // 链式精炼 **Zod v4.3.0+ 功能**： // 精确可选（可以省略字段，但不能未定义） z.string().exactOptional() // 互斥并集（必须恰好匹配） z.xor([z.string(), z.number()]) // 从 JSON 模式导入 z.fromJSONSchema({ 类型: "对象", 属性: { 名称: { 类型: "字符串" } } }) **zodResolver** 将 Zod 连接到 React Hook Form，保持类型安全 ** ** ## 注册 **注册**（对于标准 HTML 输入）： // 不受控制，最佳性能 **控制器**（对于第三方组件）： <控制器名称=“类别” 控制={form.control} render={({ field }) => } // 必须传播 {...field} /> **何时使用控制器**：React Select、日期选择器、无参考的自定义组件。否则使用“注册”。 ** ** ## 错误处理 **显示错误**： {form.formState.errors.email && {form.formState.errors.email.message}} {form.formState.errors.address?.street?.message} // 嵌套错误（使用可选链接） **服务器错误**： const onSubmit = form.handleSubmit(async (data) => { const res = wait fetch('/api/submit', { method: 'POST', body: JSON.stringify(data) }) 如果（！res.ok）{ const { 错误：serverErrors } =等待 res.json() Object.entries(serverErrors).forEach(([field, msg]) => form.setError(field, { message: msg })) } }) ** ** ## 高级模式 **useFieldArray**（动态列表）： const { 字段、追加、删除 } = useFieldArray({ control: form.control, name: 'contacts' }) {fields.map((字段，索引) => (

{/* 关键：使用 field.id，而不是索引 */} {form.formState.errors.contacts?.[index]?.name && {form.formState.errors.contacts[index].name.message}}

))} **异步验证**（去抖）： const debouncedValidation = useDebouncedCallback(() => form.trigger('用户名'), 500) **多步骤表格**： const step1 = z.object({ 名称: z.string(), 电子邮件: z.string().email() }) const step2 = z.object({ 地址: z.string() }) const fullSchema = step1.merge(step2) const nextStep = async () => { const isValid = wait form.trigger(['name', 'email']) // 验证特定字段 if (isValid) 设置步骤(2) } **条件验证**： z.discriminatedUnion('accountType', [ z.object({ accountType: z.literal('personal'), name: z.string() }), z.object({ accountType: z.literal('business'), companyName: z.string() }), ]） **带有 shouldUnregister 的条件字段**：常量形式 = useForm({ 解析器：zodResolver（架构）， shouldUnregister: false, // 字段卸载时保留值（默认） }) // 或者使用条件模式验证： z. 对象({ 显示地址：z.boolean(), 地址：z.string(), }).refine((数据) => { if (data.showAddress) { 返回数据.地址.长度> 0; } 返回真； }, { 消息：“需要地址”，路径：[“地址”]， }) ** ** ## shadcn/ui 集成 **注意**：shadcn/ui 已弃用 Form 组件。使用 Field 组件进行新的实现（查看最新文档）。 **常见导入错误**：IDE/AI 可能会从“react-hook-form”而不是从 shadcn 自动导入 `Form`。始终导入： // ✅ 正确：从“react-hook-form”导入{ useForm }；从“@/components/ui/form”导入{ Form, FormField, FormItem }; // shadcn // ❌ 错误（自动导入错误）：从“react-hook-form”导入{ useForm，Form }； **旧版表单组件**： ( <表单项> <输入{...字段} /> <表单消息/> )} /> ** ** ## 性能 * 对于标准输入，使用“register”（不受控）而不是“Controller”（受控） * 使用 `watch('email')` 而不是 `watch()` （隔离重新渲染到特定字段） * `shouldUnregister: true` 用于多步骤表单（清除卸载数据） ### 大型表格（300+ 字段） **警告**：使用解析器（Zod/Yup）并读取“formState”属性的具有 300 多个字段的表单在注册期间可能会冻结 10-15 秒。（[问题＃13129]（）） **性能特点**： *干净（没有解析器，没有读取formState）：几乎立即 * 仅使用解析器：几乎立即生效 * formState 只读：几乎立即生效 * 同时使用解析器 + formState 读取：约 9.5 秒读取 300 个字段 **解决方法**： 1. **避免解构 formState** \- 仅在需要时内联读取属性： // ❌ 300 多个字段时速度较慢： const { isDirty, isValid } = form.formState; // ✅ 快速： const handleSubmit = () => { if (!form.formState.isValid) 返回; // 仅在需要时内联读取 }; 2. **使用模式：“onSubmit”** \- 不要验证每个更改：常量形式 = useForm({ 解析器：zodResolver(largeSchema), mode: "onSubmit", // 仅在提交时验证，不在 onChange 时验证 }); 3. **拆分为子表单** \- 具有单独架构的多个较小表单： // 使用 5-6 个表单，每个表单包含 50-60 个字段，而不是一个 300 字段的表单 const form1 = useForm({ 解析器: zodResolver(schema1) }); // 字段 1-50 const form2 = useForm({ 解析器: zodResolver(schema2) }); // 字段 51-100 4. **延迟渲染字段** \- 使用选项卡/手风琴仅安装可见字段： // 仅安装活动选项卡的字段，减少初始注册时间 {activeTab === '个人' && } {activeTab === '地址' && } ** ** ## 关键规则 ✅ **始终设置defaultValues**（防止不受控制→受控制的警告） ✅ **在客户端和服务器上验证**（可以绕过客户端 - 安全！） ✅ **在 useFieldArray 中使用`field.id`作为键**（不是索引） ✅ **使用 `const form = useForm(...)`** — 通过 `form.control`、`form.handleSubmit`、`form.formState`、`form.reset()` 等访问。不要解构。 ✅ **`const onSubmit = form.handleSubmit((value) => {...})`** — 提取提交处理程序，不要将其内联到 `onSubmit={}` 中 ⚪ **`z.infer`** 是可选的 — `zodResolver` 自动推断类型。仅当您在其他地方显式需要类型（例如函数签名、道具）时才使用它。 ❌ **永远不要跳过服务器验证**（安全漏洞） ❌ **永远不要直接改变值**（使用 `form.setValue()`） ❌ **切勿混合受控 + 不受控**模式 ❌ **永远不要在 useFieldArray 中使用索引作为键** ** ** ## 已知问题（20 个已预防） 1. **Zod v4 类型推断** \- [#13109]()：显式使用 `z.infer`。在 v7.66.x+ 中已解决。 **注意**：@hookform/resolvers 与 Zod v4 存在 TypeScript 兼容性问题 ([#813]())。解决方法：使用“import { z } from 'zod/v3'”或等待解析器更新。 2. **不受控制→受控制警告** \- 始终为所有字段设置 `defaultValues` 3. **嵌套对象错误** \- 使用可选链接：`errors.address?.street?.message` 4. **数组字段重新渲染** \- 在 useFieldArray 中使用 `key={field.id}` （不是索引） 5. **异步验证竞争条件** \- 反跳验证，取消挂起的请求 6. **服务器错误映射** \- 使用 `setError()` 将服务器错误映射到字段 7. **未应用默认值** \- 在 useForm 选项中设置 `defaultValues` （不是 useState） 8. **控制器字段未更新** \- 始终在渲染函数中展开 `{...field}` 9. **useFieldArray 键警告** \- 使用 `field.id` 作为键（而不是索引） 10. **架构细化错误路径** \- 在细化中指定 `path`: `refine(..., { path: ['fieldName'] })` 11. **转换与预处理** \- 使用 `transform` 进行输出，使用 `preprocess` 进行输入 12. **多个解析器冲突** \- 使用单个解析器 (zodResolver)，根据需要组合模式 13. **Zod v4 可选字段错误** \- [#13102]()：将可选字段 (`.optional()`) 设置为空字符串 `""` 会错误地触发验证错误。解决方法：使用 `.nullish()`、`.or(z.literal(""))` 或 `z.preprocess((val) => val === "" ? undefined : val, z.email().optional())` 14. **不支持useFieldArray原始数组** \- [#12570]()：设计限制。 `useFieldArray` 仅适用于对象数组，不适用于像 `string[]` 这样的基元。解决方法：将基元包装在对象中： `[{ value: "string" }]` 而不是 `["string"]` 15. **useFieldArray SSR ID 不匹配** \- [#12782]()：SSR 的水合不匹配警告（Remix、Next.js）。服务器上生成的字段 ID 与客户端不匹配。解决方法：对字段数组使用仅客户端渲染或等待 V8（使用确定性“key”） 16. **Next.js 16 reset() 验证错误** \- [#13110]()：在服务器操作提交后调用 `form.reset()` 会导致下次提交时出现验证错误。在 v7.65.0+ 中修复。修复之前：使用 `setValue()` 而不是 `reset()` 17. **验证竞争条件** \- [#13156]()：在解析器验证期间，中间渲染其中 `isValidating=false` 但尚未填充 `errors`。不要仅从错误中得出有效性。使用： `!errors.field && !isValidating` 18. **Beta 版本中抛出的 ZodError** \- [#12816](): Zod v4 beta 版本直接抛出 `ZodError` 而不是在 `formState.errors` 中捕获。已在稳定版 Zod v4.1.x+ 中修复。避免测试版本 19. **大型表单性能** \- [#13129]()：带有解析器 + formState 的 300 多个字段读取冻结 10-15 秒。请参阅“性能”部分了解 4 种解决方法 20. **shadcn 表单导入混乱** \- IDE/AI 可能会从“react-hook-form”而不是 shadcn 自动导入 `Form`。始终从“@/components/ui/form”导入“Form”组件 ** ** ## V8（测试版）即将发生的变化 React Hook Form v8（目前处于测试版，自 v8.0.0-beta.1 起，于 2026 年 1 月 11 日发布）引入了重大更改。 [RFC 讨论 #7433]() **重大变更**： 1. **useFieldArray:`id`→`key`**: // V7: const { fields } = useFieldArray({ control, name: "items" }); fields.map(field =>

...

) // V8: const { fields } = useFieldArray({ control, name: "items" }); fields.map(field =>

...

) // keyName 属性被移除 2. **手表组件：`names`→`name`**： // V7: <手表名称={["电子邮件","密码"]} /> // V8: <手表名称={["电子邮件","密码"]} /> 3. **watch() 回调 API 已删除**： // V7: watch((数据, { 名称, 类型 }) => { console.log(数据、名称、类型); }); // V8: 使用useWatch或手动订阅 const 数据 = useWatch({ 控制 }); 使用效果（（）=> { 控制台.log(数据); }, [数据]); 4. **setValue() 不再更新 useFieldArray** ： // V7: setValue("项目", newArray); // 更新字段数组 // V8: 必须使用replace() API const { 替换 } = useFieldArray({ 控制, 名称: "items" }); 替换（新数组）； **V8 的优点**： *修复SSR水合不匹配（确定性“key”而不是随机“id”） * 改进的性能 * 更好的 TypeScript 推理 **迁移时间表**：V8 处于测试阶段。稳定发布日期待定。监视 [releases]() 以获得稳定版本。 ** ** ## 捆绑资源 **模板**：basic-form.tsx、advanced-form.tsx、shadcn-form.tsx、server-validation.ts、async-validation.tsx、dynamic-fields.tsx、multi-step-form.tsx、package.json **参考**：zod-schemas-guide.md、rhf-api-reference.md、错误处理.md、性能优化.md、shadcn-integration.md、top-errors.md **文档**： | | ** ** **许可证**：麻省理工学院 | **最后验证**：2026-01-20 | **技能版本**：2.1.0 | **更改**：添加了 8 个新的已知问题（Zod v4 可选字段错误、useFieldArray 原语限制、SSR 水合不匹配、大型表单的性能指南、Next.js 16 reset() 错误、验证竞争条件、测试版中引发的 ZodError、shadcn 导入混乱），添加了 Zod v4.3.0 功能（.exactOptional()、.xor()、z.fromJSONSchema()），添加了条件字段模式shouldUnregister，添加了 V8 beta 重大更改部分，扩展了 Zod v4 解析器兼容性说明，更新为react-hook-form@7.71.1

React Hook 表单 Zod

包含技能