| API分类| 解决的问题| |--------|--------| | Primitive 基础类型| 定义字符串、数字、布尔值、日期等 | | Collection 集合类型| 定义 Object、Array、Tuple、Record、Map、Set、Union| | Validation 校验| 对已有类型增加约束| | Transformation / Composition | optional、nullable、transform、default、pipe 等| | Schema / Error / Type| 解析、类型推导、错误处理、Metadata| ## 一、Primitive 类型 API ### 1、基础类型 | API | 参数 | 参数作用 | 使用场景 | 使用示例 | TS 对应 | | --------------- | --------- | ---------------- | -------------- | --------------- | ----------- | | `z.string()` | `params?` | 字符串配置 | 用户名、标题、ID | `z.string()` | `string` | | `z.number()` | `params?` | 数字 | 金额、数量 | `z.number()` | `number` | | `z.bigint()` | `params?` | BigInt | 超大整数 | `z.bigint()` | `bigint` | | `z.boolean()` | `params?` | 布尔值 | 开关、状态 | `z.boolean()` | `boolean` | | `z.symbol()` | `params?` | Symbol | 特殊 JS 类型 | `z.symbol()` | `symbol` | | `z.undefined()` | `params?` | undefined | 明确要求 undefined | `z.undefined()` | `undefined` | | `z.null()` | `params?` | null | 明确要求 null | `z.null()` | `null` | | `z.any()` | 无 | 接受任何值 | 极少数动态场景 | `z.any()` | `any` | | `z.unknown()` | 无 | 接受任何值但保留 unknown | 第三方未知数据 | `z.unknown()` | `unknown` | | `z.never()` | 无 | 不允许任何值 | 枚举兜底、不可达分支 | `z.never()` | `never` | ### 2、String API z.string() | API | 参数 | 作用 | 示例 | | ------------ | ---- | ---------- | ---------------------- | | `.min(n)` | 最小长度 | 至少 n 个字符 | `z.string().min(6)` | | `.max(n)` | 最大长度 | 最多 n 个字符 | `z.string().max(20)` | | `.length(n)` | 固定长度 | 必须刚好 n 个字符 | `z.string().length(6)` | ``` const username = z.string() .min(3) .max(20); ``` Pattern 校验 | API | 参数 | 作用 | 示例 | | --------------- | -------- | ---------- | -------------------------------- | | `.regex()` | `RegExp` | 正则校验 | `z.string().regex(/^[a-z]+$/)` | | `.startsWith()` | 前缀 | 必须以指定字符串开始 | `z.string().startsWith("user_")` | | `.endsWith()` | 后缀 | 必须以指定字符串结束 | `z.string().endsWith(".com")` | | `.includes()` | 子字符串 | 必须包含指定内容 | `z.string().includes("@")` | Case 校验 | API | 参数 | 作用 | 示例 | | -------------- | -- | ------ | ------------------------ | | `.uppercase()` | 无 | 必须全部大写 | `z.string().uppercase()` | | `.lowercase()` | 无 | 必须全部小写 | `z.string().lowercase()` | String Transform | API | 参数 | 作用 | 示例 | | ---------------- | ------- | ----------- | -------------------------- | | `.trim()` | 无 | 去除首尾空格 | `z.string().trim()` | | `.toLowerCase()` | 无 | 转小写 | `z.string().toLowerCase()` | | `.toUpperCase()` | 无 | 转大写 | `z.string().toUpperCase()` | | `.normalize()` | `form?` | Unicode 标准化 | `z.string().normalize()` | ### 3、String Format API | API | 参数 | 使用场景 | 示例 | | --------------- | --------- | -------------- | ------------------ | | `z.email()` | `params?` | Email | `z.email()` | | `z.uuid()` | `params?` | UUID | `z.uuid()` | | `z.url()` | `params?` | URL | `z.url()` | | `z.httpUrl()` | `params?` | HTTP/HTTPS URL | `z.httpUrl()` | | `z.hostname()` | `params?` | 域名 | `z.hostname()` | | `z.e164()` | `params?` | 国际电话号码 | `z.e164()` | | `z.emoji()` | `params?` | Emoji | `z.emoji()` | | `z.base64()` | `params?` | Base64 | `z.base64()` | | `z.base64url()` | `params?` | Base64URL | `z.base64url()` | | `z.hex()` | `params?` | 十六进制字符串 | `z.hex()` | | `z.jwt()` | `params?` | JWT | `z.jwt()` | | `z.nanoid()` | `params?` | NanoID | `z.nanoid()` | | `z.cuid()` | `params?` | CUID | `z.cuid()` | | `z.cuid2()` | `params?` | CUID2 | `z.cuid2()` | | `z.ulid()` | `params?` | ULID | `z.ulid()` | | `z.ipv4()` | `params?` | IPv4 | `z.ipv4()` | | `z.ipv6()` | `params?` | IPv6 | `z.ipv6()` | | `z.mac()` | `params?` | MAC 地址 | `z.mac()` | | `z.cidrv4()` | `params?` | IPv4 CIDR | `z.cidrv4()` | | `z.cidrv6()` | `params?` | IPv6 CIDR | `z.cidrv6()` | | `z.hash()` | hash 算法 | Hash 字符串 | `z.hash("sha256")` | ### 4、ISO 日期字符串 | API | 作用 | 示例 | | ------------------ | ------------ | ------------------------ | | `z.iso.date()` | ISO 日期 | `"2026-08-10"` | | `z.iso.time()` | ISO 时间 | `"12:30:00"` | | `z.iso.datetime()` | ISO DateTime | `"2026-08-10T12:30:00Z"` | | `z.iso.duration()` | ISO Duration | `"P3Y6M4DT12H30M5S"` | ### 5、Number API z.number() > Zod 4 的 z.number() 默认只接受有限数字，NaN 和 Infinity 不通过。 | API | 参数 | 作用 | 示例 | | ---------------- | ------------------ | --------------- | -------------------------- | | `.gt(n)` | 最小边界 | `> n` | `z.number().gt(0)` | | `.gte(n)` | 最小边界 | `>= n` | `z.number().gte(0)` | | `.lt(n)` | 最大边界 | `< n` | `z.number().lt(100)` | | `.lte(n)` | 最大边界 | `<= n` | `z.number().lte(100)` | | `.min(n)` | 最小值 | `>= n` | `z.number().min(0)` | | `.max(n)` | 最大值 | `<= n` | `z.number().max(100)` | | `.positive()` | 无 | `> 0` | `z.number().positive()` | | `.nonnegative()` | 无 | `>= 0` | `z.number().nonnegative()` | | `.negative()` | 无 | `< 0` | `z.number().negative()` | | `.nonpositive()` | 无 | `<= 0` | `z.number().nonpositive()` | | `.multipleOf(n)` | 倍数 | 必须是 n 的倍数 | `z.number().multipleOf(5)` | | `.step(n)` | 步长 | `multipleOf` 别名 | `z.number().step(5)` | ### 6、Integer | API | 作用 | 示例 | | ----------- | ----------- | ----------- | | `z.int()` | 安全整数 | `z.int()` | | `z.int32()` | 32-bit 整数范围 | `z.int32()` | ``` const Age = z.int().min(0).max(150); ``` ### 7、z.nan() ``` // 只接受NaN z.nan() ``` ### 8、BigInt z.bigint() 支持： ``` .gt() .gte() .lt() .lte() .min() .max() .positive() .nonnegative() .negative() .nonpositive() .multipleOf() .step() const id = z.bigint().positive(); ``` ### 9、Boolean z.boolean() ``` const enabled = z.boolean(); ``` ### 10、Date z.date() 支持： .min(date) .max(date) ``` const Birthday = z.date() .min(new Date("1900-01-01")) .max(new Date()); ``` 11、Enum / Literal ``` // z.enum() z.enum(["admin", "user", "guest"]) // 得到 "admin" | "user" | "guest" // 适合 const Role = z.enum([ "admin", "user", "guest" ]); ``` ``` // z.literal() z.literal("success") z.literal(200) z.literal(true) z.literal(["red", "green", "blue"]) ``` ### 12、Template Literal ``` z.templateLiteral([ "user_", z.string() ]) // 输出 `user_${string}` const Px = z.templateLiteral([ z.number(), "px" ]); // 输出 `${number}px` ``` 这是Zod 4 的新能力 ## 二、Collection / Container API ### 1、Object ``` z.object({ name: z.string(), age: z.number() }) ``` 对应 ``` { name: string; age: number; } ``` ### 2、Object 核心 API | API | 参数 | 作用 | 使用场景 | 示例 | | ------------------ | -------- | ----------- | --------- | -------------------------------- | | `z.object()` | shape | 定义对象 | API 数据、表单 | `z.object({name:z.string()})` | | `z.strictObject()` | shape | 禁止未知 key | 严格 API | `z.strictObject({...})` | | `z.looseObject()` | shape | 保留未知 key | 第三方数据 | `z.looseObject({...})` | | `.pick()` | key map | 选择字段 | DTO | `User.pick({id:true})` | | `.omit()` | key map | 删除字段 | 排除密码 | `User.omit({password:true})` | | `.partial()` | key map? | 字段 optional | PATCH | `User.partial()` | | `.required()` | key map? | 字段 required | 强制完整数据 | `User.required()` | | `.extend()` | shape | 扩展对象 | 管理员 DTO | `User.extend({role:z.string()})` | | `.shape` | 无 | 获取字段 schema | Schema 组合 | `User.shape.name` | | `.keyof()` | 无 | 获取 key enum | 动态字段 | `User.keyof()` | 3、Array ``` z.array(z.string()) ``` 对应 ``` string[] ``` | API | 参数 | 作用 | 使用场景 | 示例 | | ------------ | -------------- | ------------- | ---------- | --------------------- | | `z.array(T)` | element schema | 定义数组 | 列表 | `z.array(z.string())` | | `.array()` | 无 | 当前 schema 转数组 | 链式写法 | `z.string().array()` | | `.min(n)` | 最小长度 | 至少 n 项 | 非空列表 | `.min(1)` | | `.max(n)` | 最大长度 | 最多 n 项 | 上传限制 | `.max(10)` | | `.length(n)` | 长度 | 固定 n 项 | 固定批量数据 | `.length(3)` | | `.unwrap()` | 无 | 获取元素 schema | Schema 元编程 | `schema.unwrap()` | 4、Tuple ``` z.tuple([ z.string(), z.number() ]) ``` 对应： ``` [string, number] ``` ``` z.tuple( [z.string()], z.number() ) ``` 对应 ``` [string, ...number[]] ``` ### 5、Record ``` z.record( z.string(), z.number() ) ``` 对应 ``` Record ``` | API | 参数 | 作用 | 使用场景 | 示例 | | ---------------------- | ---------------- | ------- | ---- | ---------------------------------- | | `z.record(K,V)` | key/value schema | 动态对象 | 字典 | `z.record(z.string(),z.number())` | | `z.partialRecord(K,V)` | key/value schema | key 可缺失 | 部分配置 | `z.partialRecord(Keys,z.string())` | | `z.looseRecord(K,V)` | key/value schema | 放宽 key | 外部数据 | `z.looseRecord(...)` | **Zod 4 特别注意** ``` z.record(z.enum(["a", "b"]), z.string()) ``` 要求： ``` { a: "...", b: "..." } ``` 而： ``` z.partialRecord( z.enum(["a", "b"]), z.string() ) ``` 允许： ``` { a: "..." } ``` ### 6、Map ``` z.map( z.string(), z.number() ) ``` 对应 ``` Map ``` ### 7、Set ``` z.set(z.string()) ``` 对应： ``` Set ``` 支持： ``` .min() .max() .size() z.set(z.string()).min(1) ``` ### 8、Union ``` z.union([ z.string(), z.number() ]) ``` 对应： ``` string | number ``` 可以通过 schema.options 获取内部 schemas。 ### XOR ``` z.xor([ schemaA, schemaB ]) ``` 它与 union 的区别： ``` union → 匹配任意一个即可 xor → 必须恰好匹配一个 ``` 例如： ``` const Payment = z.xor([ z.object({ type: z.literal("card"), cardNumber: z.string() }), z.object({ type: z.literal("bank"), accountNumber: z.string() }) ]); ``` ### 10、Discriminated Union ``` z.discriminatedUnion("type", [ z.object({ type: z.literal("user"), name: z.string() }), z.object({ type: z.literal("admin"), permissions: z.array(z.string()) }) ]) ``` 适合：type/status/kind 这种带有明确 discriminator 的 API。 ### 11、Intersection ``` z.intersection(A, B) ``` 对应： ``` A & B ``` 例如： ``` const User = z.object({ name: z.string() }); const Admin = z.object({ role: z.string() }); const AdminUser = z.intersection( User, Admin ); ``` ### 12、Readonly 集合都可以： ``` z.array(z.string()).readonly() z.set(z.string()).readonly() z.map(z.string(), z.number()).readonly() z.tuple([...]).readonly() ``` 三、Validation API 这一张解决： > **“类型正确还不够，我还要限制它的值。”** --- # 1. 通用长度/数值检查很多类型共用： ```ts .min() .max() .length() ``` 但是语义根据类型不同： ```text string → 字符串长度 array → 元素数量 set → Set size number → 数值范围 date → 时间范围 ``` --- # 2. `.refine()` 最常用的自定义校验 API。 ```ts z.string().refine( value => value.length >= 8 ) ``` 带错误信息： ```ts z.string().refine( value => value.length >= 8, { error: "密码至少 8 位" } ) ``` 参数： | 参数 | 作用 | | -------- | -------------------- | | `check` | 返回 true/false 的校验函数 | | `params` | error、path、abort 等配置 | Zod 4 中推荐统一使用 `error` 配置，而不是旧的 `message` / `errorMap`。([Zod][6]) --- # 3. `.check()` Zod 4 新的底层校验组合能力： ```ts schema.check(...) ``` 例如： ```ts z.string().check( z.minLength(8), z.maxLength(100) ) ``` 也可以使用函数： ```ts z.string().check(value => { // 自定义检查 }); ``` Zod 4 内部已经将 refinement 统一为 checks 概念。([Zod][7]) --- # 4. `.overwrite()` 这是 Zod 4 很值得注意的新 API。 ```ts z.string() .overwrite(value => value.trim()) ``` 与 `.transform()` 的关键区别： ```text transform → 改变 output type overwrite → 修改值，但保持 schema 类型 ``` 例如： ```ts const schema = z.string() .overwrite(value => value.trim()); ``` 输入： ```ts " hello " ``` 输出： ```ts "hello" ``` 但仍然是： ```ts string ``` --- # 5. `.superRefine()` 仍然存在，但： > **Zod 4 已 deprecated。** 推荐： ```ts .check() ``` 不要再把： ```ts .superRefine() ``` 作为新代码的首选。官方 API 直接标记其为 deprecated。([Zod][1]) --- # 6. `z.property()` 针对对象/实例的某个属性做验证： ```ts z.instanceof(URL).check( z.property( "protocol", z.literal("https:") ) ) ``` 适合： ```text class instance DOM 对象 URL 第三方库对象 ``` Zod 4 提供了这个 API。([Zod][8]) --- # 7. `z.instanceof()` 验证： ```ts instanceof ``` 例如： ```ts class User {} const schema = z.instanceof(User); ``` 适合第三方 class： ```ts z.instanceof(URL) z.instanceof(File) z.instanceof(Date) ``` --- # 8. `z.custom()` 用于 Zod 没有原生支持的类型。 ```ts const px = z.custom<`${number}px`>( value => typeof value === "string" && /^\d+px$/.test(value) ); ``` 适合： ```text 第三方类型复杂 TS 类型模板字符串类型 ``` 但： ```ts z.custom() ``` 如果不提供校验函数，会允许任何值通过，因此需要谨慎。([Zod][8]) --- # 9. File Validation Zod 4： ```ts z.file() ``` 支持： ```ts .min(bytes) .max(bytes) .mime(type) ``` 例如： ```ts const Avatar = z.file() .max(2_000_000) .mime(["image/png", "image/jpeg"]); ``` 适合： ```text 文件上传图片上传附件校验 ``` 官方文档明确提供 `z.file()` 以及 `.min()`、`.max()`、`.mime()`。([Zod][2]) --- ## 四、Transformation / Composition API 这一张非常重要。可以把它理解成： > **“这个 Schema 不只是验证数据，还要改变数据结构。”** --- # 1. `.optional()` ```ts z.string().optional() ``` 对应： ```ts string | undefined ``` 场景： ```ts const User = z.object({ nickname: z.string().optional() }); ``` --- # 2. `.nullable()` ```ts z.string().nullable() ``` 对应： ```ts string | null ``` --- # 3. `.nullish()` ```ts z.string().nullish() ``` 对应： ```ts string | null | undefined ``` 所以： ```text optional → undefined nullable → null nullish → null + undefined ``` --- # 4. `.nonoptional()` 与 optional 相反： ```ts z.string().optional().nonoptional() ``` 要求最终必须存在。 --- # 5. `.default()` ```ts z.string().default("guest") ``` 输入： ```ts undefined ``` 输出： ```ts "guest" ``` 典型场景： ```ts const Config = z.object({ theme: z.string().default("light") }); ``` --- # 6. `.prefault()` 这是 Zod 4 一个非常值得区分的 API。 ```ts z.string() .trim() .toUpperCase() .prefault(" tuna "); ``` 输入： ```ts undefined ``` 会先使用： ```text " tuna " ``` 再执行： ```text trim ↓ toUpperCase ``` 得到： ```text "TUNA" ``` 而 `.default()` 是直接返回默认值，不经过后续 parse pipeline。官方文档明确区分了 `default` 与 `prefault`。([Zod][8]) --- # 7. `.catch()` 校验失败时返回默认值： ```ts z.number().catch(0) ``` 例如： ```ts schema.parse("hello") // 0 ``` 也可以： ```ts z.number().catch(ctx => { console.log(ctx.error); return 0; }); ``` 适合： ```text 配置文件容错数据非关键字段 ``` --- # 8. `.transform()` 执行数据转换： ```ts z.string().transform( value => value.length ) ``` 输入： ```ts "hello" ``` 输出： ```ts 5 ``` 所以： ```ts z.infer ``` 是： ```ts number ``` 而输入仍然是： ```ts string ``` --- # 9. `z.transform()` Zod 4 还可以直接定义： ```ts const schema = z.transform( value => String(value) ); ``` 例如： ```ts schema.parse(123) // "123" ``` Zod 4 把 Transform 独立成了 schema。([Zod][7]) --- # 10. `.pipe()` 连接两个 Schema： ```ts const schema = z.string() .pipe(z.transform(v => v.length)); ``` 流程： ```text input ↓ string validation ↓ transform ↓ number ``` 非常适合构建 pipeline。 --- # 11. `z.preprocess()` 在正式 schema 校验之前先处理输入： ```ts const schema = z.preprocess( value => Number(value), z.number() ); ``` 例如： ```ts schema.parse("123") ``` 得到： ```ts 123 ``` 适合： ```text Query 参数 FormData 环境变量 HTTP 请求参数 ``` Zod 4 中 `z.preprocess()` 内部已经基于 `ZodPipe` 实现。([Zod][7]) --- # 12. `z.coerce` 用于类型强制转换： ```ts z.coerce.string() z.coerce.number() z.coerce.boolean() z.coerce.bigint() ``` 例如： ```ts const age = z.coerce.number(); age.parse("18"); // 18 ``` 非常适合： ```text URL Query 参数 HTML Form 环境变量 ``` 官方说明 `z.coerce.*` 会尝试使用对应 JS 构造函数转换输入。([Zod][9]) --- # 13. `.brand()` 给类型增加 nominal typing： ```ts const UserId = z.string().brand<"UserId">(); ``` 得到： ```ts string & z.$brand<"UserId"> ``` 主要用于： ```text UserId OrderId Email Token ``` 避免不同的 string 类型混用。 --- # 14. `.readonly()` 前面集合表已经出现： ```ts z.array(z.string()).readonly() ``` 它不仅是集合 API，也是通用 Composition API。 --- # 15. `.or()` ```ts z.string().or(z.number()) ``` 等价于： ```ts z.union([ z.string(), z.number() ]) ``` 适合链式写法。 --- # 16. `.and()` ```ts A.and(B) ``` 等价于： ```ts z.intersection(A, B) ``` 例如： ```ts z.object({ name: z.string() }).and( z.object({ age: z.number() }) ); ``` --- # 17. `z.codec()` Zod 4 还提供 Codec，用于： > **双向转换** 例如： ```text decode JSON → Domain Object encode Domain Object → JSON ``` 与： ```ts .transform() ``` 的区别： ```text transform → 单向 codec → 双向 ``` 官方专门将 Codec 作为 Zod 4 的双向转换能力。([Zod][10]) --- # 第五张：Schema / Error / Type API 这是最容易被忽略、但实际项目最重要的一张。 --- # 1. Parsing API 所有 Schema 最核心的几个方法： | API | 参数 | 返回 | 使用场景 | | ------------------- | ----- | --------------- | ---------------------- | | `.parse()` | input | output / throw | 确信异常可抛出 | | `.safeParse()` | input | Result | 推荐业务 API | | `.parseAsync()` | input | Promise | async transform/refine | | `.safeParseAsync()` | input | Promise | 异步安全解析 | --- ## `.parse()` ```ts const result = User.parse(input); ``` 成功： ```ts User ``` 失败： ```ts throw ZodError ``` --- ## `.safeParse()` ```ts const result = User.safeParse(input); ``` 结果： ```ts { success: true, data: ... } ``` 或者： ```ts { success: false, error: ... } ``` 实际业务中非常推荐： ```ts const result = schema.safeParse(data); if (!result.success) { return result.error; } return result.data; ``` 官方 Basic Usage 也明确将 `parse` / `safeParse` 作为核心使用方式。([Zod][11]) --- # 2. Async Parsing 如果 Schema 中存在： ```ts async refine ``` 或者： ```ts async transform ``` 必须： ```ts await schema.parseAsync(data) ``` 或者： ```ts await schema.safeParseAsync(data) ``` 否则会出现运行时错误。([Zod][2]) --- # 3. Type Inference ## `z.infer` 最常用： ```ts const User = z.object({ name: z.string(), age: z.number() }); type User = z.infer; ``` 得到： ```ts type User = { name: string; age: number; } ``` --- # 4. `z.input` 当存在 transform 时非常重要。 ```ts const schema = z.string() .transform(v => v.length); ``` 那么： ```ts type Input = z.input; ``` 是： ```ts string ``` --- # 5. `z.output` ```ts type Output = z.output; ``` 得到： ```ts number ``` 所以： ```text z.input → Schema 接收什么 z.output → Schema 最终产生什么 z.infer → output 的别名/常用写法 ``` --- # 6. JSON Zod 4： ```ts z.json() ``` 验证任意 JSON-compatible 数据： ```text string number boolean null array object ``` 例如： ```ts const jsonSchema = z.json(); ``` 官方说明它本质上是递归 JSON Schema 的便利 API。([Zod][2]) --- # 7. `z.lazy()` 用于递归 Schema： ```ts const Category = z.object({ name: z.string(), children: z.array( z.lazy(() => Category) ) }); ``` 适合： ```text 树目录评论 AST 嵌套菜单 ``` --- # 8. Function Schema Zod 4： ```ts z.function({ input: [z.string()], output: z.number() }); ``` 表示： ```ts (string) => number ``` 然后： ```ts const fn = schema.implement( value => value.length ); ``` Zod 会自动验证： ```text 输入 ↓ 函数 ↓ 输出 ``` 还支持： ```ts .implementAsync() ``` 处理异步函数。([Zod][2]) --- # 9. Error API Zod 4 最重要的错误 API： | API | 参数 | 作用 | 场景 | | ------------------- | ------ | -------- | ---------- | | `ZodError` | issues | Zod 错误对象 | 捕获异常 | | `z.treeifyError()` | error | 树形错误 | 嵌套表单 | | `z.flattenError()` | error | 扁平错误 | 表单 | | `z.prettifyError()` | error | 人类可读文本 | 日志 | | `z.formatError()` | error | 旧格式化 | deprecated | | `error.issues` | 无 | 原始错误数组 | 自定义错误处理 | --- ## `treeifyError()` 例如： ```ts const result = schema.safeParse(data); if (!result.success) { const tree = z.treeifyError(result.error); } ``` 结果类似： ```ts { errors: [], properties: { username: { errors: ["Invalid input"] }, profile: { properties: { age: { errors: ["Too small"] } } } } } ``` 非常适合： ```text 复杂嵌套表单复杂 API 递归数据 ``` --- # 10. `flattenError()` 适合普通表单： ```ts const flattened = z.flattenError(error); ``` 得到： ```ts { formErrors: [], fieldErrors: { username: ["Invalid input"], email: ["Invalid email"] } } ``` 这对 React/Vue 表单非常实用。([Zod][12]) --- # 11. `prettifyError()` ```ts z.prettifyError(error) ``` 得到类似： ```text ✖ Invalid input: expected string, received number → at username ✖ Invalid input: expected number, received string → at age ``` 适合： ```text CLI 日志开发环境 debug ``` Zod 4 新增并推荐这个 API。([Zod][12]) --- # 12. `formatError()` ```ts z.formatError(error) ``` ⚠️ **Deprecated** Zod 4 推荐： ```ts z.treeifyError(error) ``` 官方已经明确建议迁移。([Zod][12]) --- # 13. Metadata / Registry Zod 4 新增了一套很重要的 Metadata API。 ```ts const registry = z.registry(); ``` 然后： ```ts registry.add(schema, metadata); registry.get(schema); registry.has(schema); registry.remove(schema); registry.clear(); ``` 例如： ```ts const registry = z.registry<{ description: string }>(); const Email = z.email(); registry.add(Email, { description: "用户邮箱" }); ``` --- # 14. `.register()` ```ts schema.register( registry, metadata ) ``` 例如： ```ts Email.register( registry, { description: "用户邮箱" } ); ``` 特别注意： ```text .register() ``` 返回的是： > **原来的 schema** 而 `.meta()` / `.describe()` 会返回新的 schema 实例。([Zod][13]) --- # 15. `z.globalRegistry` Zod 内置： ```ts z.globalRegistry ``` 适合： ```text JSON Schema OpenAPI 代码生成文档 AI Structured Output ``` 例如： ```ts const Email = z.email().register( z.globalRegistry, { id: "email", title: "Email", description: "用户邮箱" } ); ``` --- # 16. `.meta()` 推荐使用： ```ts schema.meta({ id: "user_email", description: "用户邮箱" }); ``` 读取： ```ts schema.meta(); ``` Zod 4 官方推荐 `.meta()` 作为 Metadata 的主要使用方式。([Zod][13]) --- # 17. `.describe()` 仍然支持： ```ts schema.describe("用户邮箱") ``` 但官方建议： ```ts schema.meta({ description: "用户邮箱" }) ``` `.describe()` 本质上是向 `z.globalRegistry` 注册 description 的快捷方式。([Zod][13]) --- # 18. Schema Utility API | API | 作用 | 示例 | | --------------- | -------------- | ------------------------------ | | `.clone()` | 克隆 Schema | `schema.clone()` | | `.brand()` | Brand 类型 | `z.string().brand<"UserId">()` | | `.isOptional()` | 判断 optional | `schema.isOptional()` | | `.isNullable()` | 判断 nullable | `schema.isNullable()` | | `.check()` | 增加校验 | `schema.check(...)` | | `.apply()` | 应用外部 Schema 函数 | `schema.apply(fn)` | 其中 `.apply()` 特别适合封装公共校验： ```ts function commonNumberChecks< T extends z.ZodNumber >(schema: T) { return schema .min(0) .max(100); } const score = z.number() .apply(commonNumberChecks); ``` 官方当前 API 中仍提供 `.apply()`。([Zod][2]) --- # 最终版：Zod 4 API 导航地图如果你以后只想记一张图，我建议记这个： ```text Zod 4 │ ├── ① Primitive │ │ │ ├── string │ ├── number │ ├── bigint │ ├── boolean │ ├── symbol │ ├── undefined │ ├── null │ ├── any │ ├── unknown │ ├── never │ │ │ ├── email │ ├── uuid │ ├── url │ ├── ipv4 / ipv6 │ ├── date │ ├── enum │ ├── literal │ └── templateLiteral │ ├── ② Collection │ │ │ ├── object │ │ ├── pick │ │ ├── omit │ │ ├── partial │ │ ├── required │ │ └── extend │ │ │ ├── array │ ├── tuple │ ├── record │ ├── partialRecord │ ├── looseRecord │ ├── map │ ├── set │ ├── union │ ├── xor │ ├── discriminatedUnion │ └── intersection │ ├── ③ Validation │ │ │ ├── min / max / length │ ├── gt / gte / lt / lte │ ├── positive / negative │ ├── multipleOf / step │ ├── regex │ ├── refine │ ├── check │ ├── overwrite │ ├── property │ ├── instanceof │ ├── custom │ └── file │ ├── ④ Transformation │ │ │ ├── optional │ ├── nullable │ ├── nullish │ ├── nonoptional │ ├── default │ ├── prefault │ ├── catch │ ├── transform │ ├── preprocess │ ├── coerce │ ├── pipe │ ├── or │ ├── and │ ├── brand │ ├── readonly │ └── codec │ └── ⑤ Schema / Error / Type │ ├── parse ├── safeParse ├── parseAsync ├── safeParseAsync │ ├── z.infer ├── z.input ├── z.output │ ├── z.lazy ├── z.json ├── z.function │ ├── ZodError ├── treeifyError ├── flattenError ├── prettifyError │ ├── registry ├── globalRegistry ├── register ├── meta └── describe ``` --- # Zod 4 新旧 API 特别标记如果你是拿这份表**学习 Zod 4，而不是学习 Zod 3**，这一部分建议重点记忆： | 旧 API / 写法 | Zod 4 建议 | | -------------------- | ---------------------------------- | | `.merge()` | `.extend()` / object spread | | `.strict()` | `z.strictObject()` | | `.passthrough()` | `z.looseObject()` | | `.deepPartial()` | 删除 | | `.superRefine()` | `.check()` | | `message` | `error` | | `errorMap` | `error` | | `invalid_type_error` | `error` | | `required_error` | `error` | | `z.formatError()` | `z.treeifyError()` | | `z.record(schema)` | `z.record(keySchema, valueSchema)` | Zod 4 对 error customization 进行了统一，并移除了/调整了多项 Zod 3 API。([Zod][7]) --- ## 实际项目中的组合案例以 **NestJS / Node.js API + Vue3 前端**为例： ```ts import * as z from "zod"; const CreateUserSchema = z.object({ username: z.string() .min(3) .max(20), email: z.email(), age: z.int() .min(18) .max(100), role: z.enum([ "admin", "user" ]), tags: z.array( z.string() ).min(1), permissions: z.set( z.string() ), metadata: z.record( z.string(), z.string() ), avatar: z.file() .max(2_000_000) .mime([ "image/png", "image/jpeg" ]), nickname: z.string() .trim() .optional(), status: z.enum([ "active", "inactive" ]).default("active") }); ``` 然后： ```ts type CreateUser = z.infer< typeof CreateUserSchema >; ``` 学习 Zod 的方式：**不要把 Zod 当成几十个 API 的集合，而要把它理解成“TypeScript 类型 + Runtime Validation + Transformation + Type Inference”的组合系统。**

Zod/v4速查表