zod-validation

Zod 验证（v4）

适用于 TypeScript 的类型安全模式验证。Zod v4 引入了顶层格式函数、z.stringbool()、z.iso.* 日期格式、z.overwrite() 转换、z.file()、z.toJSONSchema()、基于 getter 的递归类型、.meta()，以及统一的 error 函数。

包： zod（小体积版本另有 zod/mini）

快速参考

模式	用途
z.object({ ... })	定义对象模式
z.string()、z.number()	基本类型
z.email()、z.url()、z.uuid()	顶层字符串格式（v4）
z.iso.date()、z.iso.datetime()	ISO 日期／时间格式（v4）
z.int()、z.float32()、z.int32()	固定宽度数字格式（v4）
z.templateLiteral([...])	模板字面量类型验证（v4）
z.enum([...])、z.literal()	枚举和字面量
z.union([...])、z.discriminatedUnion()	联合类型
z.array()、z.tuple()	数组和元组类型
z.record()、z.map()	键值集合
.optional()、.nullable()	可选和可空修饰符
.default()、.catch()	默认值和回退值
.prefault()	解析前默认值（经模式解析，v4）
z.coerce.number()	验证前进行类型强制转换
z.stringbool()	将字符串解析为布尔值（v4）
.transform()、.overwrite()	输出转换
z.pipe()	链接模式（输出作为下一个模式的输入）
.refine()、.superRefine()	自定义验证逻辑
.parse()、.safeParse()	验证并提取数据
z.infer<typeof Schema>	从模式提取 TypeScript 类型
z.input<>、z.output<>	转换后的输入类型与输出类型
z.file()	文件实例验证（v4）
z.toJSONSchema()	将模式转换为 JSON Schema（v4）
.meta()、.describe()	为模式附加元数据（v4）
z.prettifyError()	以人类可读的格式呈现错误（v4）
z.treeifyError()	结构化错误树（取代 .format()，v4）
z.registry()	类型化模式注册表（v4）
{ error: (issue) => ... }	统一的错误自定义方式（v4）
基于 getter 的递归	无需 z.lazy() 的递归类型（v4）
z.globalRegistry	全局模式元数据注册表（v4）
z.config(z.locales.en())	国际化错误消息（v4）

常见错误

错误	修正
z.string().email()	z.email()（v4 顶层格式）
z.string().url()	z.url()（v4 顶层格式）
使用 parse 却不加 try/catch	使用 safeParse 处理错误
忘记添加 .optional()	字段可能为 undefined 时添加
对未知数据使用 z.any()	使用 z.unknown()，以确保类型安全
对相同类型的值进行更改时使用 .transform()	使用 .overwrite()（可自省，v4）
字符串缺少 .min(1)	默认情况下，空字符串也能通过 z.string()
z.number().parse(Infinity)	v4 中的 z.number() 会拒绝 Infinity
对浮点数使用 z.number().safe()	v4 中 .safe() 等同于 .int()（不支持浮点数）
对递归类型使用 z.lazy()	在 v4 中使用 getter 语法（保留对象方法）
required_error / invalid_type_error	在 v4 中使用统一的 error 函数
.refine(fn, (val) => ({ message }))	已移除第二个参数为函数的重载；请使用 .superRefine()
在 schema 上使用 errorMap	在 v4 中已由 error 函数取代
z.record(z.string()) 单参数形式	v4 要求两个参数：z.record(z.string(), z.string())
在 ZodError 上使用 .format() / .flatten()	已弃用；请在 v4 中使用 z.treeifyError(err)
.default() 使用输入类型的值	v4 的 .default() 使用输出类型；输入类型请使用 .prefault()

委派

此技能适用于 Zod schema 定义、验证、解析、类型推断、强制转换、错误格式化、元数据和 JSON Schema 转换。对于表单集成，请委派给 tanstack-form 技能。

参考资料

• Schema 类型 — 基本类型、字符串格式、数字格式、模板字面量、对象、数组、枚举、联合类型、记录、可选、可空
• 转换与解析 — 强制转换、stringbool、转换、overwrite、管道、细化、解析、类型推断
• 错误处理 — 统一的 error 函数、prettifyError、treeifyError、ZodError、错误格式化、国际化
• 常见模式 — 表单验证、API 响应、环境变量、schema 组合、递归类型、品牌类型
• 元数据与 JSON Schema — meta、describe、globalRegistry、toJSONSchema、文件验证、Zod Mini