zod-validation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zod Validation (v4)

Type-safe schema validation for TypeScript. Zod v4 introduces top-level format functions,

z.stringbool()

z.iso.*

date formats,

z.overwrite()

transforms,

z.file()

z.toJSONSchema()

, getter-based recursive types,

.meta()

, and the unified

error

function.

Package:

zod

(also

zod/mini

for smaller bundles)

为TypeScript提供类型安全的Schema验证。Zod v4 引入了顶层格式函数、

z.stringbool()

、

z.iso.*

日期格式、

z.overwrite()

转换方法、

z.file()

、

z.toJSONSchema()

、基于 getter 的递归类型、

.meta()

方法以及统一的

error

函数。

包名：

zod

（也可使用

zod/mini

以获得更小的打包体积）

Quick Reference

快速参考

Pattern	Usage
`z.object({ ... })`	Define object schemas
`z.string()` , `z.number()`	Primitive types
`z.email()` , `z.url()` , `z.uuid()`	Top-level string formats (v4)
`z.iso.date()` , `z.iso.datetime()`	ISO date/time formats (v4)
`z.int()` , `z.float32()` , `z.int32()`	Fixed-width number formats (v4)
`z.templateLiteral([...])`	Template literal type validation (v4)
`z.enum([...])` , `z.literal()`	Enums and literals
`z.union([...])` , `z.discriminatedUnion()`	Union types
`z.array()` , `z.tuple()`	Array and tuple types
`z.record()` , `z.map()`	Key-value collections
`.optional()` , `.nullable()`	Optional and nullable modifiers
`.default()` , `.catch()`	Default values and fallbacks
`.prefault()`	Pre-parse default (parsed through schema, v4)
`z.coerce.number()`	Type coercion before validation
`z.stringbool()`	String-to-boolean parsing (v4)
`.transform()` , `.overwrite()`	Output transforms
`z.pipe()`	Chain schemas (output feeds next input)
`.refine()` , `.superRefine()`	Custom validation logic
`.parse()` , `.safeParse()`	Validate and extract data
`z.infer<typeof Schema>`	Extract TypeScript type from schema
`z.input<>` , `z.output<>`	Input vs output types with transforms
`z.file()`	File instance validation (v4)
`z.toJSONSchema()`	Convert schema to JSON Schema (v4)
`.meta()` , `.describe()`	Attach metadata to schemas (v4)
`z.prettifyError()`	Human-readable error formatting (v4)
`z.treeifyError()`	Structured error tree (replaces .format(), v4)
`z.registry()`	Typed schema registry (v4)
`{ error: (issue) => ... }`	Unified error customization (v4)
Getter-based recursion	Recursive types without `z.lazy()` (v4)
`z.globalRegistry`	Global schema metadata registry (v4)
`z.config(z.locales.en())`	Internationalized error messages (v4)

语法模式	用途
`z.object({ ... })`	定义对象Schema
`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()`	预解析默认值（会通过Schema解析，v4新增）
`z.coerce.number()`	验证前进行类型转换
`z.stringbool()`	字符串转布尔值解析（v4新增）
`.transform()` , `.overwrite()`	输出数据转换
`z.pipe()`	链式Schema（前一个的输出作为后一个的输入）
`.refine()` , `.superRefine()`	自定义验证逻辑
`.parse()` , `.safeParse()`	验证并提取数据
`z.infer<typeof Schema>`	从Schema中提取TypeScript类型
`z.input<>` , `z.output<>`	带转换的输入与输出类型
`z.file()`	文件实例验证（v4新增）
`z.toJSONSchema()`	将Schema转换为JSON Schema（v4新增）
`.meta()` , `.describe()`	为Schema附加元数据（v4新增）
`z.prettifyError()`	人类可读的错误格式化（v4新增）
`z.treeifyError()`	结构化错误树（替代原.format()方法，v4新增）
`z.registry()`	类型化Schema注册表（v4新增）
`{ error: (issue) => ... }`	统一的错误定制（v4新增）
基于getter的递归	无需 `z.lazy()` 的递归类型（v4新增）
`z.globalRegistry`	全局Schema元数据注册表（v4新增）
`z.config(z.locales.en())`	多语言错误提示（v4新增）

Common Mistakes

常见错误

Mistake	Fix
`z.string().email()`	`z.email()` (v4 top-level format)
`z.string().url()`	`z.url()` (v4 top-level format)
Using `parse` without try/catch	Use `safeParse` for error handling
Forgetting `.optional()`	Add when field may be undefined
`z.any()` for unknown data	Use `z.unknown()` for type-safe unknown
`.transform()` for same-type changes	Use `.overwrite()` (introspectable, v4)
Missing `.min(1)` on strings	Empty strings pass `z.string()` by default
`z.number().parse(Infinity)`	`z.number()` rejects `Infinity` in v4
`z.number().safe()` for floats	`.safe()` equals `.int()` in v4 (no floats)
`z.lazy()` for recursive types	Use getter syntax in v4 (retains object methods)
`required_error` / `invalid_type_error`	Use unified `error` function in v4
`.refine(fn, (val) => ({ message }))`	Function-as-second-arg overload removed; use `.superRefine()`
`errorMap` on schemas	Replaced by `error` function in v4
`z.record(z.string())` single arg	v4 requires two args: `z.record(z.string(), z.string())`
`.format()` / `.flatten()` on ZodError	Deprecated; use `z.treeifyError(err)` in v4
`.default()` with input type value	v4 `.default()` uses output type; use `.prefault()` for input

错误写法	修复方案
`z.string().email()`	`z.email()` （v4 顶层格式）
`z.string().url()`	`z.url()` （v4 顶层格式）
使用 `parse` 而不添加try/catch包裹	使用 `safeParse` 进行错误处理
忘记添加 `.optional()`	当字段可能为undefined时添加该修饰符
对未知数据使用 `z.any()`	对类型安全的未知数据使用 `z.unknown()`
对同类型修改使用 `.transform()`	使用 `.overwrite()` （可被 introspect，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()`

Delegation

职责划分

Use this skill for Zod schema definition, validation, parsing, type inference, coercion, error formatting, metadata, and JSON Schema conversion. For form integration, delegate to the tanstack-form skill.

本技能适用于Zod Schema定义、验证、解析、类型推断、类型转换、错误格式化、元数据处理以及JSON Schema转换。如需表单集成，请委托给tanstack-form技能处理。

References

参考资料

Schema Types — primitives, string formats, number formats, template literals, objects, arrays, enums, unions, records, optional, nullable
Transforms and Parsing — coercion, stringbool, transforms, overwrite, pipe, refinements, parsing, type inference
Error Handling — unified error function, prettifyError, treeifyError, ZodError, error formatting, internationalization
Common Patterns — form validation, API responses, environment variables, schema composition, recursive types, branded types
Metadata and JSON Schema — meta, describe, globalRegistry, toJSONSchema, file validation, Zod Mini

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