定义模式

要验证数据，你必须首先定义一个模式。模式表示类型，从简单的原始值到复杂的嵌套对象和数组。

🌐 To validate data, you must first define a schema. Schemas represent types, from simple primitive values to complex nested objects and arrays.

原语

🌐 Primitives

import * as z from "zod";
 
// primitive types
z.string();
z.number();
z.bigint();
z.boolean();
z.symbol();
z.undefined();
z.null();

强制转换

🌐 Coercion

要将输入数据强制转换为适当的类型，请改用 z.coerce：

🌐 To coerce input data to the appropriate type, use z.coerce instead:

z.coerce.string();    // String(input)
z.coerce.number();    // Number(input)
z.coerce.boolean();   // Boolean(input)
z.coerce.bigint();    // BigInt(input)

这些模式的强制类型会尝试将输入值转换为适当的类型。

🌐 The coerced variant of these schemas attempts to convert the input value to the appropriate type.

const schema = z.coerce.string();
 
schema.parse("tuna");    // => "tuna"
schema.parse(42);        // => "42"
schema.parse(true);      // => "true"
schema.parse(null);      // => "null"

这些强制模式的输入类型默认是 unknown。要指定更具体的输入类型，请传递一个泛型参数：

🌐 The input type of these coerced schemas is unknown by default. To specify a more specific input type, pass a generic parameter:

const A = z.coerce.number();
type AInput = z.input<typeof A>; // => unknown
 
const B = z.coerce.number<number>();
type BInput = z.input<typeof B>; // => number

字面量

🌐 Literals

字面模式表示一种字面类型，如 "hello world" 或 5。

🌐 Literal schemas represent a literal type, like "hello world" or 5.

const tuna = z.literal("tuna");
const twelve = z.literal(12);
const twobig = z.literal(2n);
const tru = z.literal(true);

表示 JavaScript 字面量 null 和 undefined ：

🌐 To represent the JavaScript literals null and undefined:

z.null();
z.undefined();
z.void(); // equivalent to z.undefined()

要允许多个字面量值：

🌐 To allow multiple literal values:

const colors = z.literal(["red", "green", "blue"]);
 
colors.parse("green"); // ✅
colors.parse("yellow"); // ❌

要从字面模式中提取允许值的集合：

🌐 To extract the set of allowed values from a literal schema:

colors.values; // => Set<"red" | "green" | "blue">

字符串

🌐 Strings

Zod 提供了一些内置的字符串验证和转换 API。要执行一些常见的字符串验证：

🌐 Zod provides a handful of built-in string validation and transform APIs. To perform some common string validations:

z.string().max(5);
z.string().min(5);
z.string().length(5);
z.string().regex(/^[a-z]+$/);
z.string().startsWith("aaa");
z.string().endsWith("zzz");
z.string().includes("---");
z.string().uppercase();
z.string().lowercase();

要执行一些简单的字符串转换：

🌐 To perform some simple string transforms:

z.string().trim(); // trim whitespace
z.string().toLowerCase(); // toLowerCase
z.string().toUpperCase(); // toUpperCase
z.string().normalize(); // normalize unicode characters

字符串格式

🌐 String formats

要针对某些常见字符串格式进行验证：

🌐 To validate against some common string formats:

z.email();
z.uuid();
z.url();
z.httpUrl();       // http or https URLs only
z.hostname();
z.emoji();         // validates a single emoji character
z.base64();
z.base64url();
z.hex();
z.jwt();
z.nanoid();
z.cuid();
z.cuid2();
z.ulid();
z.ipv4();
z.ipv6();
z.mac();
z.cidrv4();        // ipv4 CIDR block
z.cidrv6();        // ipv6 CIDR block
z.hash("sha256");  // or "sha1", "sha384", "sha512", "md5"
z.iso.date();
z.iso.time();
z.iso.datetime();
z.iso.duration();

电子邮件

🌐 Emails

要验证电子邮件地址：

🌐 To validate email addresses:

z.email();

默认情况下，Zod 使用一个相对严格的电子邮件正则表达式，旨在验证包含常见字符的普通电子邮件地址。它大致相当于 Gmail 强制执行的规则。要了解有关此正则表达式的更多信息，请参阅 这篇文章。

🌐 By default, Zod uses a comparatively strict email regex designed to validate normal email addresses containing common characters. It's roughly equivalent to the rules enforced by Gmail. To learn more about this regex, refer to this post.

/^(?!\.)(?!.*\.\.)([a-z0-9_'+\-\.]*)[a-z0-9_+-]@([a-z0-9][a-z0-9\-]*\.)+[a-z]{2,}$/i

要自定义电子邮件验证行为，你可以将自定义正则表达式传递给 pattern 参数。

🌐 To customize the email validation behavior, you can pass a custom regular expression to the pattern param.

z.email({ pattern: /your regex here/ });

Zod 导出了几个你可以使用的有用的正则表达式。

🌐 Zod exports several useful regexes you could use.

// Zod's default email regex
z.email();
z.email({ pattern: z.regexes.email }); // equivalent
 
// the regex used by browsers to validate input[type=email] fields
// https://web.nodejs.cn/en-US/docs/Web/HTML/Element/input/email
z.email({ pattern: z.regexes.html5Email });
 
// the classic emailregex.com regex (RFC 5322)
z.email({ pattern: z.regexes.rfc5322Email });
 
// a loose regex that allows Unicode (good for intl emails)
z.email({ pattern: z.regexes.unicodeEmail });

UUIDs

要验证 UUID：

🌐 To validate UUIDs:

z.uuid();

要指定特定的 UUID 版本：

🌐 To specify a particular UUID version:

// supports "v1", "v2", "v3", "v4", "v5", "v6", "v7", "v8"
z.uuid({ version: "v4" });
 
// for convenience
z.uuidv4();
z.uuidv6();
z.uuidv7();

RFC 9562/4122 UUID 规范要求第 8 个字节的前两位为 10。其他类似 UUID 的标识符不强制此约束。要验证任何类似 UUID 的标识符：

🌐 The RFC 9562/4122 UUID spec requires the first two bits of byte 8 to be 10. Other UUID-like identifiers do not enforce this constraint. To validate any UUID-like identifier:

z.guid();

网址

🌐 URLs

要验证任何与 WHATWG 兼容的 URL：

🌐 To validate any WHATWG-compatible URL:

const schema = z.url();
 
schema.parse("https://example.com"); // ✅
schema.parse("http://localhost"); // ✅
schema.parse("mailto:noreply@zod.dev"); // ✅

如你所见，这是相当宽松的。内部使用 new URL() 构造函数来验证输入；这种行为可能在不同的平台和运行时中有所不同，但它是在任何给定的 JS 运行时/引擎上验证 URI/URL 的最严格方法。

🌐 As you can see this is quite permissive. Internally this uses the new URL() constructor to validate inputs; this behavior may differ across platforms and runtimes but it's the mostly rigorous way to validate URIs/URLs on any given JS runtime/engine.

要根据特定的正则表达式验证主机名：

🌐 To validate the hostname against a specific regex:

const schema = z.url({ hostname: /^example\.com$/ });
 
schema.parse("https://example.com"); // ✅
schema.parse("https://zombo.com"); // ❌

要根据特定的正则表达式验证协议，请使用 protocol 参数。

🌐 To validate the protocol against a specific regex, use the protocol param.

const schema = z.url({ protocol: /^https$/ });
 
schema.parse("https://example.com"); // ✅
schema.parse("http://example.com"); // ❌

const httpUrl = z.url({
  protocol: /^https?$/,
  hostname: z.regexes.domain
});

/^([a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/

要标准化 URL，请使用 normalize 标志。这将用 new URL() 返回的 标准化 URL 覆盖输入值。

🌐 To normalize URLs, use the normalize flag. This will overwrite the input value with the normalized URL returned by new URL().

new URL("HTTP://ExAmPle.com:80/./a/../b?X=1#f oo").href
// => "http://example.com/b?X=1#f%20oo"

ISO 日期时间

🌐 ISO datetimes

正如你可能注意到的，Zod 字符串包含一些与日期/时间相关的验证。这些验证是基于正则表达式的，因此它们不像完整的日期/时间库那样严格。然而，对于验证用户输入来说，它们非常方便。

🌐 As you may have noticed, Zod string includes a few date/time related validations. These validations are regular expression based, so they are not as strict as a full date/time library. However, they are very convenient for validating user input.

z.iso.datetime() 方法强制执行 ISO 8601；默认情况下，不允许使用时区偏移：

🌐 The z.iso.datetime() method enforces ISO 8601; by default, no timezone offsets are allowed:

const datetime = z.iso.datetime();
 
datetime.parse("2020-01-01T06:15:00Z"); // ✅
datetime.parse("2020-01-01T06:15:00.123Z"); // ✅
datetime.parse("2020-01-01T06:15:00.123456Z"); // ✅ (arbitrary precision)
datetime.parse("2020-01-01T06:15:00+02:00"); // ❌ (offsets not allowed)
datetime.parse("2020-01-01T06:15:00"); // ❌ (local not allowed)

要允许时区偏移：

🌐 To allow timezone offsets:

const datetime = z.iso.datetime({ offset: true });
 
// allows timezone offsets
datetime.parse("2020-01-01T06:15:00+02:00"); // ✅
 
// basic offsets not allowed
datetime.parse("2020-01-01T06:15:00+02");    // ❌
datetime.parse("2020-01-01T06:15:00+0200");  // ❌
 
// Z is still supported
datetime.parse("2020-01-01T06:15:00Z"); // ✅ 

要允许非限定（无时区）日期时间：

🌐 To allow unqualified (timezone-less) datetimes:

const schema = z.iso.datetime({ local: true });
schema.parse("2020-01-01T06:15:01"); // ✅
schema.parse("2020-01-01T06:15"); // ✅ seconds optional

用于限制允许的时间 precision。默认情况下，秒是可选的，并允许任意的亚秒精度。

🌐 To constrain the allowable time precision. By default, seconds are optional and arbitrary sub-second precision is allowed.

const a = z.iso.datetime();
a.parse("2020-01-01T06:15Z"); // ✅
a.parse("2020-01-01T06:15:00Z"); // ✅
a.parse("2020-01-01T06:15:00.123Z"); // ✅
 
const b = z.iso.datetime({ precision: -1 }); // minute precision (no seconds)
b.parse("2020-01-01T06:15Z"); // ✅
b.parse("2020-01-01T06:15:00Z"); // ❌
b.parse("2020-01-01T06:15:00.123Z"); // ❌
 
const c = z.iso.datetime({ precision: 0 }); // second precision only
c.parse("2020-01-01T06:15Z"); // ❌
c.parse("2020-01-01T06:15:00Z"); // ✅
c.parse("2020-01-01T06:15:00.123Z"); // ❌
 
const d = z.iso.datetime({ precision: 3 }); // millisecond precision only
d.parse("2020-01-01T06:15Z"); // ❌
d.parse("2020-01-01T06:15:00Z"); // ❌
d.parse("2020-01-01T06:15:00.123Z"); // ✅

ISO 日期

🌐 ISO dates

z.iso.date() 方法验证格式为 YYYY-MM-DD 的字符串。

🌐 The z.iso.date() method validates strings in the format YYYY-MM-DD.

const date = z.iso.date();
 
date.parse("2020-01-01"); // ✅
date.parse("2020-1-1"); // ❌
date.parse("2020-01-32"); // ❌

ISO 时间

🌐 ISO times

z.iso.time() 方法用于验证 HH:MM[:SS[.s+]] 格式的字符串。默认情况下，秒是可选的，子秒小数也是可选的。

🌐 The z.iso.time() method validates strings in the format HH:MM[:SS[.s+]]. By default seconds are optional, as are sub-second decimals.

const time = z.iso.time();
 
time.parse("03:15"); // ✅
time.parse("03:15:00"); // ✅
time.parse("03:15:00.9999999"); // ✅ (arbitrary precision)

不允许任何形式的偏移。

🌐 No offsets of any kind are allowed.

time.parse("03:15:00Z"); // ❌ (no `Z` allowed)
time.parse("03:15:00+02:00"); // ❌ (no offsets allowed)

使用 precision 参数来限制允许的小数精度。

🌐 Use the precision parameter to constrain the allowable decimal precision.

z.iso.time({ precision: -1 }); // HH:MM (minute precision)
z.iso.time({ precision: 0 });  // HH:MM:SS (second precision)
z.iso.time({ precision: 1 });  // HH:MM:SS.s (decisecond precision)
z.iso.time({ precision: 2 });  // HH:MM:SS.ss (centisecond precision)
z.iso.time({ precision: 3 });  // HH:MM:SS.sss (millisecond precision)

IP 地址

🌐 IP addresses

const ipv4 = z.ipv4();
ipv4.parse("192.168.0.0"); // ✅
 
const ipv6 = z.ipv6();
ipv6.parse("2001:db8:85a3::8a2e:370:7334"); // ✅

IP 地址块 (CIDR)

🌐 IP blocks (CIDR)

验证使用 CIDR 表示法 指定的 IP 地址范围。

🌐 Validate IP address ranges specified with CIDR notation.

const cidrv4 = z.cidrv4();
cidrv4.parse("192.168.0.0/24"); // ✅
 
const cidrv6 = z.cidrv6();
cidrv6.parse("2001:db8::/32"); // ✅

MAC 地址

🌐 MAC Addresses

验证标准 48 位 MAC 地址 IEEE 802。

🌐 Validate standard 48-bit MAC address IEEE 802.

const mac = z.mac(); 
mac.parse("00:1A:2B:3C:4D:5E");  // ✅
mac.parse("00-1a-2b-3c-4d-5e");  // ❌ colon-delimited by default
mac.parse("001A:2B3C:4D5E");     // ❌ standard formats only
mac.parse("00:1A:2b:3C:4d:5E");  // ❌ no mixed case
 
// custom delimiter
const dashMac = z.mac({ delimiter: "-" });
dashMac.parse("00-1A-2B-3C-4D-5E"); // ✅

JWTs

验证 JSON Web 令牌。

🌐 Validate JSON Web Tokens.

z.jwt();
z.jwt({ alg: "HS256" });

哈希值

🌐 Hashes

为了验证加密哈希值：

🌐 To validate cryptographic hash values:

z.hash("md5");
z.hash("sha1");
z.hash("sha256");
z.hash("sha384");
z.hash("sha512");

默认情况下，z.hash() 期望十六进制编码，这是常规做法。你可以使用 enc 参数指定不同的编码：

🌐 By default, z.hash() expects hexadecimal encoding, as is conventional. You can specify a different encoding with the enc parameter:

z.hash("sha256", { enc: "hex" });       // default
z.hash("sha256", { enc: "base64" });    // base64 encoding
z.hash("sha256", { enc: "base64url" }); // base64url encoding (no padding)

自定义格式

🌐 Custom formats

定义你自己的字符串格式：

🌐 To define your own string formats:

const coolId = z.stringFormat("cool-id", ()=>{
  // arbitrary validation here
  return val.length === 100 && val.startsWith("cool-");
});
 
// a regex is also accepted
z.stringFormat("cool-id", /^cool-[a-z0-9]{95}$/);

该模式将产生 "invalid_format" 问题，这些问题比通过细化或 z.custom() 产生的 "custom" 错误更具描述性。

🌐 This schema will produce "invalid_format" issues, which are more descriptive than the "custom" errors produced by refinements or z.custom().

myFormat.parse("invalid input!");
// ZodError: [
//   {
//     "code": "invalid_format",
//     "format": "cool-id",
//     "path": [],
//     "message": "Invalid cool-id"
//   }
// ]

模板字面量

🌐 Template literals

定义一个模板字面量模式：

🌐 To define a template literal schema:

const schema = z.templateLiteral([ "hello, ", z.string(), "!" ]);
// `hello, ${string}!`

z.templateLiteral API 可以处理任意数量的字符串字面量（例如 "hello"）和模式。任何具有可分配给 string | number | bigint | boolean | null | undefined 的推断类型的模式都可以传递。

🌐 The z.templateLiteral API can handle any number of string literals (e.g. "hello") and schemas. Any schema with an inferred type that's assignable to string | number | bigint | boolean | null | undefined can be passed.

z.templateLiteral([ "hi there" ]);
// `hi there`
 
z.templateLiteral([ "email: ", z.string() ]);
// `email: ${string}`
 
z.templateLiteral([ "high", z.literal(5) ]);
// `high5`
 
z.templateLiteral([ z.nullable(z.literal("grassy")) ]);
// `grassy` | `null`
 
z.templateLiteral([ z.number(), z.enum(["px", "em", "rem"]) ]);
// `${number}px` | `${number}em` | `${number}rem`

数字

🌐 Numbers

使用 z.number() 来验证数字。它允许任何有限数字。

🌐 Use z.number() to validate numbers. It allows any finite number.

const schema = z.number();
 
schema.parse(3.14);      // ✅
schema.parse(NaN);       // ❌
schema.parse(Infinity);  // ❌

Zod 实现了一些特定于数字的验证：

🌐 Zod implements a handful of number-specific validations:

z.number().gt(5);
z.number().gte(5);                     // alias .min(5)
z.number().lt(5);
z.number().lte(5);                     // alias .max(5)
z.number().positive();                 // alias .gt(0)
z.number().nonnegative();    
z.number().negative(); 
z.number().nonpositive(); 
z.number().multipleOf(5);              // alias .step(5)

如果（出于某种原因）你想验证 NaN，请使用 z.nan()。

🌐 If (for some reason) you want to validate NaN, use z.nan().

z.nan().parse(NaN);              // ✅
z.nan().parse("anything else");  // ❌

整数

🌐 Integers

要验证整数：

🌐 To validate integers:

z.int();     // restricts to safe integer range
z.int32();   // restrict to int32 range

BigInts

要验证 BigInt：

🌐 To validate BigInts:

z.bigint();

Zod 包含一些特定于 bigint 的验证。

🌐 Zod includes a handful of bigint-specific validations.

z.bigint().gt(5n);
z.bigint().gte(5n);                    // alias `.min(5n)`
z.bigint().lt(5n);
z.bigint().lte(5n);                    // alias `.max(5n)`
z.bigint().positive();                 // alias `.gt(0n)`
z.bigint().nonnegative(); 
z.bigint().negative(); 
z.bigint().nonpositive(); 
z.bigint().multipleOf(5n);             // alias `.step(5n)`

布尔值

🌐 Booleans

要验证布尔值：

🌐 To validate boolean values:

z.boolean().parse(true); // => true
z.boolean().parse(false); // => false

日期

🌐 Dates

使用 z.date() 来验证 Date 实例。

🌐 Use z.date() to validate Date instances.

z.date().safeParse(new Date()); // success: true
z.date().safeParse("2022-01-12T06:15:00.000Z"); // success: false

要自定义错误消息：

🌐 To customize the error message:

z.date({
  error: issue => issue.input === undefined ? "Required" : "Invalid date"
});

Zod 提供了一些特定于日期的验证。

🌐 Zod provides a handful of date-specific validations.

z.date().min(new Date("1900-01-01"), { error: "Too old!" });
z.date().max(new Date(), { error: "Too young!" });

枚举

🌐 Enums

使用 z.enum 将输入与一组固定的允许 string 值进行验证。

🌐 Use z.enum to validate inputs against a fixed set of allowable string values.

const FishEnum = z.enum(["Salmon", "Tuna", "Trout"]);
 
FishEnum.parse("Salmon"); // => "Salmon"
FishEnum.parse("Swordfish"); // => ❌

const fish = ["Salmon", "Tuna", "Trout"];
 
const FishEnum = z.enum(fish);
type FishEnum = z.infer<typeof FishEnum>; // string

const fish = ["Salmon", "Tuna", "Trout"] as const;
 
const FishEnum = z.enum(fish);
type FishEnum = z.infer<typeof FishEnum>; // "Salmon" | "Tuna" | "Trout"

支持类似枚举的对象字面量（{ [key: string]: string | number }）。

🌐 Enum-like object literals ({ [key: string]: string | number }) are supported.

const Fish = {
  Salmon: 0,
  Tuna: 1
} as const
 
const FishEnum = z.enum(Fish)
FishEnum.parse(Fish.Salmon); // => ✅
FishEnum.parse(0); // => ✅
FishEnum.parse(2); // => ❌

你还可以传入外部声明的 TypeScript 枚举。

🌐 You can also pass in an externally-declared TypeScript enum.

enum Fish {
  Salmon = 0,
  Tuna = 1
}
 
const FishEnum = z.enum(Fish);
FishEnum.parse(Fish.Salmon); // => ✅
FishEnum.parse(0); // => ✅
FishEnum.parse(2); // => ❌

enum Fish {
  Salmon = "Salmon",
  Tuna = "Tuna",
  Trout = "Trout",
}
 
const FishEnum = z.enum(Fish);

.enum

要将模式的值提取为类似枚举的对象：

🌐 To extract the schema's values as an enum-like object:

const FishEnum = z.enum(["Salmon", "Tuna", "Trout"]);
 
FishEnum.enum;
// => { Salmon: "Salmon", Tuna: "Tuna", Trout: "Trout" }

.exclude()

要创建新的枚举架构并排除某些值：

🌐 To create a new enum schema, excluding certain values:

const FishEnum = z.enum(["Salmon", "Tuna", "Trout"]);
const TunaOnly = FishEnum.exclude(["Salmon", "Trout"]);

.extract()

要创建新的枚举架构并提取某些值：

🌐 To create a new enum schema, extracting certain values:

const FishEnum = z.enum(["Salmon", "Tuna", "Trout"]);
const SalmonAndTroutOnly = FishEnum.extract(["Salmon", "Trout"]);

字符串布尔

🌐 Stringbools [#stringbool]

在某些情况下（例如解析环境变量），将某些字符串“布尔值”解析为普通的 boolean 值是有价值的。为了支持这一点，Zod 4 引入了 z.stringbool()：

🌐 In some cases (e.g. parsing environment variables) it's valuable to parse certain string "boolish" values to a plain boolean value. To support this, Zod 4 introduces z.stringbool():

const strbool = z.stringbool();
 
strbool.parse("true")         // => true
strbool.parse("1")            // => true
strbool.parse("yes")          // => true
strbool.parse("on")           // => true
strbool.parse("y")            // => true
strbool.parse("enabled")      // => true
 
strbool.parse("false");       // => false
strbool.parse("0");           // => false
strbool.parse("no");          // => false
strbool.parse("off");         // => false
strbool.parse("n");           // => false
strbool.parse("disabled");    // => false
 
strbool.parse(/* anything else */); // ZodError<[{ code: "invalid_value" }]>

自定义真值和假值：

🌐 To customize the truthy and falsy values:

// these are the defaults
z.stringbool({
  truthy: ["true", "1", "yes", "on", "y", "enabled"],
  falsy: ["false", "0", "no", "off", "n", "disabled"],
});

默认情况下，模式是不区分大小写的；所有输入在与 truthy/falsy 值比较之前都会被转换为小写。要使其区分大小写：

🌐 By default the schema is case-insensitive; all inputs are converted to lowercase before comparison to the truthy/falsy values. To make it case-sensitive:

z.stringbool({
  case: "sensitive"
});

可选值

🌐 Optionals

使模式可选（即允许 undefined 输入）。

🌐 To make a schema optional (that is, to allow undefined inputs).

z.optional(z.literal("yoda")); // or z.literal("yoda").optional()

这将返回一个封装原始模式的 ZodOptional 实例。要提取内部模式：

🌐 This returns a ZodOptional instance that wraps the original schema. To extract the inner schema:

optionalYoda.unwrap(); // ZodLiteral<"yoda">

可空值

🌐 Nullables

使模式可为空（即允许输入 null）。

🌐 To make a schema nullable (that is, to allow null inputs).

z.nullable(z.literal("yoda")); // or z.literal("yoda").nullable()

这将返回一个封装原始模式的 ZodNullable 实例。要提取内部模式：

🌐 This returns a ZodNullable instance that wraps the original schema. To extract the inner schema:

nullableYoda.unwrap(); // ZodLiteral<"yoda">

将空值转换为空值

🌐 Nullish

要使模式 nullish（既可选又可为 null）：

🌐 To make a schema nullish (both optional and nullable):

const nullishYoda = z.nullish(z.literal("yoda"));

有关 nullish 概念的更多信息，请参阅 TypeScript 手册。

🌐 Refer to the TypeScript manual for more about the concept of nullish.

未知

🌐 Unknown

Zod 旨在一对一地映射 TypeScript 的类型系统。因此，Zod 提供了用于表示以下特殊类型的 API：

🌐 Zod aims to mirror TypeScript's type system one-to-one. As such, Zod provides APIs to represent the following special types:

// allows any values
z.any(); // inferred type: `any`
z.unknown(); // inferred type: `unknown`

从不

🌐 Never

任何值都无法通过验证。

🌐 No value will pass validation.

z.never(); // inferred type: `never`

对象

🌐 Objects

定义一个对象类型：

🌐 To define an object type:

  // all properties are required by default
  const Person = z.object({
    name: z.string(),
    age: z.number(),
  });
 
  type Person = z.infer<typeof Person>;
  // => { name: string; age: number; }

By default, all properties are required. To make certain properties optional:

const Dog = z.object({
  name: z.string(),
  age: z.number().optional(),
});
 
Dog.parse({ name: "Yeller" }); // ✅

默认情况下，未识别的键会从解析结果中去除：

🌐 By default, unrecognized keys are stripped from the parsed result:

Dog.parse({ name: "Yeller", extraKey: true });
// => { name: "Yeller" }

z.strictObject

定义一个严格的模式，当发现未知键时会抛出错误：

🌐 To define a strict schema that throws an error when unknown keys are found:

const StrictDog = z.strictObject({
  name: z.string(),
});
 
StrictDog.parse({ name: "Yeller", extraKey: true });
// ❌ throws

z.looseObject

定义一个允许未知键通过的宽松模式：

🌐 To define a loose schema that allows unknown keys to pass through:

const LooseDog = z.looseObject({
  name: z.string(),
});
 
LooseDog.parse({ name: "Yeller", extraKey: true });
// => { name: "Yeller", extraKey: true }

.catchall()

定义一个通用模式，用于验证任何未识别的键：

🌐 To define a catchall schema that will be used to validate any unrecognized keys:

const DogWithStrings = z.object({
  name: z.string(),
  age: z.number().optional(),
}).catchall(z.string());
 
DogWithStrings.parse({ name: "Yeller", extraKey: "extraValue" }); // ✅
DogWithStrings.parse({ name: "Yeller", extraKey: 42 }); // ❌

.shape

访问内部模式：

🌐 To access the internal schemas:

Dog.shape.name; // => string schema
Dog.shape.age; // => number schema

.keyof()

要从对象模式的键创建 ZodEnum 模式：

🌐 To create a ZodEnum schema from the keys of an object schema:

const keySchema = Dog.keyof();
// => ZodEnum<["name", "age"]>

.extend()

要向对象架构添加其他字段：

🌐 To add additional fields to an object schema:

const DogWithBreed = Dog.extend({
  breed: z.string(),
});

这个 API 可用于覆盖现有字段！使用这个功能时要小心！如果两个模式共享键，B 将覆盖 A。

🌐 This API can be used to overwrite existing fields! Be careful with this power! If the two schemas share keys, B will override A.

const DogWithBreed = z.object({ // or z.strictObject() or z.looseObject()...
  ...Dog.shape,
  breed: z.string(),
});

const DogWithBreed = z.object({
  ...Animal.shape,
  ...Pet.shape,
  breed: z.string(),
});

.safeExtend()

.safeExtend() 方法的工作方式类似于 .extend()，但它不会让你用不可赋值的模式覆盖现有属性。换句话说，.safeExtend() 的结果将具有推断类型，该类型 extends 原始类型（在 TypeScript 的意义上）。

🌐 The .safeExtend() method works similarly to .extend(), but it won't let you overwrite an existing property with a non-assignable schema. In other words, the result of .safeExtend() will have an inferred type that extends the original (in the TypeScript sense).

z.object({ a: z.string() }).safeExtend({ a: z.string().min(5) }); // ✅
z.object({ a: z.string() }).safeExtend({ a: z.any() }); // ✅
z.object({ a: z.string() }).safeExtend({ a: z.number() });
//                                       ^  ❌ ZodNumber is not assignable 

使用 .safeExtend() 来扩展包含细化的模式。（常规的 .extend() 在用于包含细化的模式时会抛出错误。）

🌐 Use .safeExtend() to extend schemas that contain refinements. (Regular .extend() will throw an error when used on schemas with refinements.)

const Base = z.object({
  a: z.string(),
  b: z.string()
}).refine(user => user.a === user.b);
 
// Extended inherits the refinements of Base
const Extended = Base.safeExtend({
  a: z.string().min(10)
});

.pick()

受 TypeScript 内置的 Pick 和 Omit 工具类型启发，Zod 提供了用于从对象模式中选择和省略某些键的专用 API。

🌐 Inspired by TypeScript's built-in Pick and Omit utility types, Zod provides dedicated APIs for picking and omitting certain keys from an object schema.

从此初始模式开始：

🌐 Starting from this initial schema:

const Recipe = z.object({
  title: z.string(),
  description: z.string().optional(),
  ingredients: z.array(z.string()),
});
// { title: string; description?: string | undefined; ingredients: string[] }

To pick certain keys:

const JustTheTitle = Recipe.pick({ title: true });

.omit()

要省略某些键：

🌐 To omit certain keys:

const RecipeNoId = Recipe.omit({ id: true });

.partial()

为了方便，Zod 提供了一个专用的 API，用于将部分或全部属性设为可选，这一设计灵感来源于内置的 TypeScript 工具类型 Partial。

🌐 For convenience, Zod provides a dedicated API for making some or all properties optional, inspired by the built-in TypeScript utility type Partial.

要使所有字段可选：

🌐 To make all fields optional:

const PartialRecipe = Recipe.partial();
// { title?: string | undefined; description?: string | undefined; ingredients?: string[] | undefined }

要使某些属性可选：

🌐 To make certain properties optional:

const RecipeOptionalIngredients = Recipe.partial({
  ingredients: true,
});
// { title: string; description?: string | undefined; ingredients?: string[] | undefined }

.required()

Zod 提供了一个 API，用于将某些或所有属性设置为必需，其灵感来自 TypeScript 的 Required 工具类型。

🌐 Zod provides an API for making some or all properties required, inspired by TypeScript's Required utility type.

要使所有属性必填：

🌐 To make all properties required:

const RequiredRecipe = Recipe.required();
// { title: string; description: string; ingredients: string[] }

要使某些属性成为必需属性：

🌐 To make certain properties required:

const RecipeRequiredDescription = Recipe.required({description: true});
// { title: string; description: string; ingredients: string[] }

递归对象

🌐 Recursive objects

要定义自引用类型，在键上使用 getter。这让 JavaScript 能在运行时解析循环模式。

🌐 To define a self-referential type, use a getter on the key. This lets JavaScript resolve the cyclical schema at runtime.

const Category = z.object({
  name: z.string(),
  get subcategories(){
    return z.array(Category)
  }
});
 
type Category = z.infer<typeof Category>;
// { name: string; subcategories: Category[] }

你也可以表示相互递归类型：

🌐 You can also represent mutually recursive types:

const User = z.object({
  email: z.email(),
  get posts(){
    return z.array(Post)
  }
});
 
const Post = z.object({
  title: z.string(),
  get author(){
    return User
  }
});

所有对象 API（.pick()、.omit()、.required()、.partial() 等）都按预期工作。

🌐 All object APIs (.pick(), .omit(), .required(), .partial(), etc.) work as you'd expect.

循环错误

🌐 Circularity errors

由于 TypeScript 的限制，递归类型推断可能会很棘手，并且它只在某些情况下有效。一些更复杂的类型可能会触发像这样的递归类型错误：

🌐 Due to TypeScript limitations, recursive type inference can be finicky, and it only works in certain scenarios. Some more complicated types may trigger recursive type errors like this:

const Activity = z.object({
  name: z.string(),
  get subactivities() {
    // ^ ❌ 'subactivities' implicitly has return type 'any' because it does not
    // have a return type annotation and is referenced directly or indirectly
    // in one of its return expressions.ts(7023)
 
    return z.nullable(z.array(Activity));
  },
});

在这些情况下，你可以在有问题的 getter 上添加类型注释来解析错误：

🌐 In these cases, you can resolve the error with a type annotation on the offending getter:

const Activity = z.object({
  name: z.string(),
  get subactivities(): z.ZodNullable<z.ZodArray<typeof Activity>> {
    return z.nullable(z.array(Activity));
  },
});

数组

🌐 Arrays

定义一个数组模式：

🌐 To define an array schema:

const stringArray = z.array(z.string()); // or z.string().array()

访问数组元素的内部模式。

🌐 To access the inner schema for an element of the array.

stringArray.unwrap(); // => string schema

Zod 实现了一些特定于数组的验证：

🌐 Zod implements a number of array-specific validations:

z.array(z.string()).min(5); // must contain 5 or more items
z.array(z.string()).max(5); // must contain 5 or fewer items
z.array(z.string()).length(5); // must contain 5 items exactly

元组

🌐 Tuples

与数组不同，元组通常是固定长度的数组，每个索引指定不同的模式。

🌐 Unlike arrays, tuples are typically fixed-length arrays that specify different schemas for each index.

const MyTuple = z.tuple([
  z.string(),
  z.number(),
  z.boolean()
]);
 
type MyTuple = z.infer<typeof MyTuple>;
// [string, number, boolean]

添加可变（“剩余”）参数：

🌐 To add a variadic ("rest") argument:

const variadicTuple = z.tuple([z.string()], z.number());
// => [string, ...number[]];

联合

🌐 Unions

联合类型（A | B）表示逻辑“或”。Zod 联合模式会按顺序检查输入是否符合每个选项。第一个验证成功的值将被返回。

🌐 Union types (A | B) represent a logical "OR". Zod union schemas will check the input against each option in order. The first value that validates successfully is returned.

const stringOrNumber = z.union([z.string(), z.number()]);
// string | number
 
stringOrNumber.parse("foo"); // passes
stringOrNumber.parse(14); // passes

要提取内部选项模式：

🌐 To extract the internal option schemas:

stringOrNumber.options; // [ZodString, ZodNumber]

异或 (XOR)

🌐 Exclusive unions (XOR)

异或联合（XOR）是一种联合，其中必须恰好有一个选项匹配。与任何选项匹配即可成功的常规联合不同，如果没有选项匹配或者有多个选项匹配，z.xor() 将失败。

🌐 An exclusive union (XOR) is a union where exactly one option must match. Unlike regular unions that succeed when any option matches, z.xor() fails if zero options match OR if multiple options match.

const schema = z.xor([z.string(), z.number()]);
 
schema.parse("hello"); // ✅ passes
schema.parse(42);      // ✅ passes
schema.parse(true);    // ❌ fails (zero matches)

当你想要确保选项之间的互斥性时，此功能非常有用：

🌐 This is useful when you want to ensure mutual exclusivity between options:

// Validate that exactly ONE of these matches
const payment = z.xor([
  z.object({ type: z.literal("card"), cardNumber: z.string() }),
  z.object({ type: z.literal("bank"), accountNumber: z.string() }),
]);
 
payment.parse({ type: "card", cardNumber: "1234" }); // ✅ passes

如果输入可以匹配多个选项，z.xor() 将会失败：

🌐 If the input could match multiple options, z.xor() will fail:

const overlapping = z.xor([z.string(), z.any()]);
overlapping.parse("hello"); // ❌ fails (matches both string and any)

可区分联合

🌐 Discriminated unions

一个判别联合是一种特殊类型的联合，其中 a) 所有选项都是对象模式，并且 b) 共享特定的键（称为“判别器”）。根据判别器键的值，TypeScript 能够像预期的那样“缩小”类型签名。

🌐 A discriminated union is a special kind of union in which a) all the options are object schemas that b) share a particular key (the "discriminator"). Based on the value of the discriminator key, TypeScript is able to "narrow" the type signature as you'd expect.

type MyResult =
  | { status: "success"; data: string }
  | { status: "failed"; error: string };
 
function handleResult(result: MyResult){
  if(result.status === "success"){
    result.data; // string
  } else {
    result.error; // string
  }
}

你可以用一个普通的 z.union() 来表示它。但普通联合类型是天真的——它会按顺序检查输入是否符合每个选项，并返回第一个通过的选项。这对于大的联合类型来说可能很慢。

🌐 You could represent it with a regular z.union(). But regular unions are naive—they check the input against each option in order and return the first one that passes. This can be slow for large unions.

所以 Zod 提供了一个 z.discriminatedUnion() API，该 API 使用 鉴别键 来提高解析的效率。

🌐 So Zod provides a z.discriminatedUnion() API that uses a discriminator key to make parsing more efficient.

const MyResult = z.discriminatedUnion("status", [
  z.object({ status: z.literal("success"), data: z.string() }),
  z.object({ status: z.literal("failed"), error: z.string() }),
]);

每个选项都应该是一个对象模式，其判别属性（在上面的示例中为status）对应某个字面值或一组值，通常是z.enum()、z.literal()、z.null()或z.undefined()。

🌐 Each option should be an object schema whose discriminator prop (status in the example above) corresponds to some literal value or set of values, usually z.enum(), z.literal(), z.null(), or z.undefined().

交叉点

🌐 Intersections

交叉类型（A & B）表示逻辑“与”。

🌐 Intersection types (A & B) represent a logical "AND".

const a = z.union([z.number(), z.string()]);
const b = z.union([z.number(), z.boolean()]);
const c = z.intersection(a, b);
 
type c = z.infer<typeof c>; // => number

这对于交叉两种对象类型很有用。

🌐 This can be useful for intersecting two object types.

const Person = z.object({ name: z.string() });
type Person = z.infer<typeof Person>;
 
const Employee = z.object({ role: z.string() });
type Employee = z.infer<typeof Employee>;
 
const EmployedPerson = z.intersection(Person, Employee);
type EmployedPerson = z.infer<typeof EmployedPerson>;
// Person & Employee

记录

🌐 Records

记录模式用于验证诸如 Record<string, string> 的类型。

🌐 Record schemas are used to validate types such as Record<string, string>.

z.record

const IdCache = z.record(z.string(), z.string());
type IdCache = z.infer<typeof IdCache>; // Record<string, string>
 
IdCache.parse({
  carlotta: "77d2586b-9e8e-4ecf-8b21-ea7e0530eadd",
  jimmie: "77d2586b-9e8e-4ecf-8b21-ea7e0530eadd",
});

键模式可以是任何可分配给 string | number | symbol 的 Zod 模式。

🌐 The key schema can be any Zod schema that is assignable to string | number | symbol.

const Keys = z.union([z.string(), z.number(), z.symbol()]);
const AnyObject = z.record(Keys, z.unknown());
// Record<string | number | symbol, unknown>

要创建包含枚举定义的键的对象架构：

🌐 To create an object schemas containing keys defined by an enum:

const Keys = z.enum(["id", "name", "email"]);
const Person = z.record(Keys, z.string());
// { id: string; name: string; email: string }

新 — 从 v4.2 开始，Zod 正确支持记录中的数字键，这种方式更接近 TypeScript 本身的行为。当 number 模式用作记录键时，它将验证该键是否为有效的“数字字符串”。额外的数字约束（最小值、最大值、步长等）也将被验证。

const numberKeys = z.record(z.number(), z.string());
numberKeys.parse({ 
  1: "one", // ✅
  2: "two", // ✅
  "1.5": "one", // ✅
  "-3": "two", // ✅
  abc: "one" // ❌
});
 
// further validation is also supported
const intKeys = z.record(z.int().step(1).min(0).max(10), z.string());
intKeys.parse({ 
  0: "zero", // ✅
  1: "one", // ✅
  2: "two", // ✅
  12: "twelve", // ❌
  abc: "one" // ❌
});

z.partialRecord

type MyRecord = Record<"a" | "b", string>;
const myRecord: MyRecord = { a: "foo", b: "bar" }; // ✅
const myRecord: MyRecord = { a: "foo" }; // ❌ missing required key `b`

如果你想要一个部分记录类型，请使用 z.partialRecord()。这会跳过 Zod 通常在 z.enum() 和 z.literal() 键模式下执行的特殊完整性检查。

🌐 If you want a partial record type, use z.partialRecord(). This skips the special exhaustiveness checks Zod normally runs with z.enum() and z.literal() key schemas.

const Keys = z.enum(["id", "name", "email"]).or(z.never()); 
const Person = z.partialRecord(Keys, z.string());
// { id?: string; name?: string; email?: string }

z.looseRecord

默认情况下，z.record() 会在键不符合键模式时产生错误。使用 z.looseRecord() 可以让不匹配的键保持不变地通过。这在与交集结合以建模多个模式属性时特别有用：

🌐 By default, z.record() errors on keys that don't match the key schema. Use z.looseRecord() to pass through non-matching keys unchanged. This is particularly useful when combined with intersections to model multiple pattern properties:

const schema = z
  .object({ name: z.string() })
  .and(z.looseRecord(z.string().regex(/_phone$/), z.e164()));
 
type schema = z.infer<typeof schema>;
// => { name: string } & Record<string, string>
 
schema.parse({ 
  name: "John",
  home_phone: "+12345678900",     // validated as phone number
  work_phone: "+12345678900",     // validated as phone number
});

映射

🌐 Maps

const StringNumberMap = z.map(z.string(), z.number());
type StringNumberMap = z.infer<typeof StringNumberMap>; // Map<string, number>
 
const myMap: StringNumberMap = new Map();
myMap.set("one", 1);
myMap.set("two", 2);
 
StringNumberMap.parse(myMap);

集合

🌐 Sets

const NumberSet = z.set(z.number());
type NumberSet = z.infer<typeof NumberSet>; // Set<number>
 
const mySet: NumberSet = new Set();
mySet.add(1);
mySet.add(2);
NumberSet.parse(mySet);

可以使用以下实用方法进一步约束设置的 Schema。

🌐 Set schemas can be further constrained with the following utility methods.

z.set(z.string()).min(5); // must contain 5 or more items
z.set(z.string()).max(5); // must contain 5 or fewer items
z.set(z.string()).size(5); // must contain 5 items exactly

文件

🌐 Files

验证 File 实例：

🌐 To validate File instances:

const fileSchema = z.file();
 
fileSchema.min(10_000); // minimum .size (bytes)
fileSchema.max(1_000_000); // maximum .size (bytes)
fileSchema.mime("image/png"); // MIME type
fileSchema.mime(["image/png", "image/jpeg"]); // multiple MIME types

Promise

🌐 Promises

Instanceof

你可以使用 z.instanceof 来检查输入是否为某个类的实例。这对于验证输入是否符合从第三方库导出的类非常有用。

🌐 You can use z.instanceof to check that the input is an instance of a class. This is useful to validate inputs against classes that are exported from third-party libraries.

class Test {
  name: string;
}
 
const TestSchema = z.instanceof(Test);
 
TestSchema.parse(new Test()); // ✅
TestSchema.parse("whatever"); // ❌

属性

🌐 Property

要根据 Zod 模式验证类实例的特定属性：

🌐 To validate a particular property of a class instance against a Zod schema:

const blobSchema = z.instanceof(URL).check(
  z.property("protocol", z.literal("https:" as string, "Only HTTPS allowed"))
);
 
blobSchema.parse(new URL("https://example.com")); // ✅
blobSchema.parse(new URL("http://example.com")); // ❌

z.property() API 可用于任何数据类型（但与 z.instanceof() 结合使用时最为有用）。

🌐 The z.property() API works with any data type (but it's most useful when used in conjunction with z.instanceof()).

const blobSchema = z.string().check(
  z.property("length", z.number().min(10))
);
 
blobSchema.parse("hello there!"); // ✅
blobSchema.parse("hello."); // ❌

细化

🌐 Refinements

每个 Zod 模式都会存储一个 refinements 数组。Refinements 是一种执行 Zod 未提供原生 API 的自定义验证的方法。

🌐 Every Zod schema stores an array of refinements. Refinements are a way to perform custom validation that Zod doesn't provide a native API for.

.refine()

const myString = z.string().refine((val) => val.length <= 255);

error

要自定义错误消息：

🌐 To customize the error message:

const myString = z.string().refine((val) => val.length > 8, { 
  error: "Too short!" 
});

abort

默认情况下，检查中的验证问题被视为可继续的；也就是说，即使其中一个检查导致验证错误，Zod仍会按顺序执行所有检查。这通常是理想的，因为这意味着 Zod 可以一次性显示尽可能多的错误。

🌐 By default, validation issues from checks are considered continuable; that is, Zod will execute all checks in sequence, even if one of them causes a validation error. This is usually desirable, as it means Zod can surface as many errors as possible in one go.

const myString = z.string()
  .refine((val) => val.length > 8, { error: "Too short!" })
  .refine((val) => val === val.toLowerCase(), { error: "Must be lowercase" });
  
 
const result = myString.safeParse("OH NO");
result.error?.issues;
/* [
  { "code": "custom", "message": "Too short!" },
  { "code": "custom", "message": "Must be lowercase" }
] */

要将特定的精炼标记为不可继续，请使用 abort 参数。如果检查失败，验证将终止。

🌐 To mark a particular refinement as non-continuable, use the abort parameter. Validation will terminate if the check fails.

const myString = z.string()
  .refine((val) => val.length > 8, { error: "Too short!", abort: true })
  .refine((val) => val === val.toLowerCase(), { error: "Must be lowercase", abort: true });
 
 
const result = myString.safeParse("OH NO");
result.error?.issues;
// => [{ "code": "custom", "message": "Too short!" }]

path

要自定义错误路径，请使用 path 参数。这通常只在对象模式的上下文中有用。

🌐 To customize the error path, use the path parameter. This is typically only useful in the context of object schemas.

const passwordForm = z
  .object({
    password: z.string(),
    confirm: z.string(),
  })
  .refine((data) => data.password === data.confirm, {
    message: "Passwords don't match",
    path: ["confirm"], // path of error
  });

这将设置关联问题中的 path 参数：

🌐 This will set the path parameter in the associated issue:

const result = passwordForm.safeParse({ password: "asdf", confirm: "qwer" });
result.error.issues;
/* [{
  "code": "custom",
  "path": [ "confirm" ],
  "message": "Passwords don't match"
}] */

要定义一个异步精炼，只需传入一个 async 函数：

🌐 To define an asynchronous refinement, just pass an async function:

const userId = z.string().refine(async (id) => {
  // verify that ID exists in database
  return true;
});

const result = await userId.parseAsync("abc123");

when

默认情况下，如果已经遇到任何不可继续的问题，则不会运行细化。Zod 会小心确保值的类型签名正确，然后才将其传递到任何细化函数中。

🌐 By default, refinements don't run if any non-continuable issues have already been encountered. Zod is careful to ensure the type signature of the value is correct before passing it into any refinement functions.

const schema = z.string().refine((val) => {
  return val.length > 8
});
 
schema.parse(1234); // invalid_type: refinement won't be executed

在某些情况下，你可能希望对细化何时运行有更精细的控制。例如，考虑这个“确认密码”检查：

🌐 In some cases, you want finer control over when refinements run. For instance consider this "password confirm" check:

const schema = z
  .object({
    password: z.string().min(8),
    confirmPassword: z.string(),
    anotherField: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "Passwords do not match",
    path: ["confirmPassword"],
  });
 
schema.parse({
  password: "asdf",
  confirmPassword: "asdf",
  anotherField: 1234 // ❌ this error will prevent the password check from running
});

anotherField 上的错误将阻止密码确认检查的执行，即使该检查不依赖 anotherField。要控制精炼何时运行，请使用 when 参数：

🌐 An error on anotherField will prevent the password confirmation check from executing, even though the check doesn't depend on anotherField. To control when a refinement will run, use the when parameter:

const schema = z
  .object({
    password: z.string().min(8),
    confirmPassword: z.string(),
    anotherField: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "Passwords do not match",
    path: ["confirmPassword"],
 
    // run if password & confirmPassword are valid
    when(payload) { 
      return schema 
        .pick({ password: true, confirmPassword: true }) 
        .safeParse(payload.value).success; 
    },  
  });
 
schema.parse({
  password: "asdf",
  confirmPassword: "asdf",
  anotherField: 1234 // ❌ this error will not prevent the password check from running
});

.superRefine()

常规的 .refine API 仅生成一个带有 "custom" 错误代码的问题，但 .superRefine() 可以使用 Zod 的任何内部问题类型创建多个问题。

🌐 The regular .refine API only generates a single issue with a "custom" error code, but .superRefine() makes it possible to create multiple issues using any of Zod's internal issue types.

const UniqueStringArray = z.array(z.string()).superRefine((val, ctx) => {
  if (val.length > 3) {
    ctx.addIssue({
      code: "too_big",
      maximum: 3,
      origin: "array",
      inclusive: true,
      message: "Too many items 😡",
      input: val,
    });
  }
 
  if (val.length !== new Set(val).size) {
    ctx.addIssue({
      code: "custom",
      message: `No duplicates allowed.`,
      input: val,
    });
  }
});
 

.check()

编解码器

🌐 Codecs

编解码器是一种特殊类型的模式，它在两个其他模式之间实现双向转换。

🌐 Codecs are a special kind of schema that implement bidirectional transformations between two other schemas.

const stringToDate = z.codec(
  z.iso.datetime(),  // input schema: ISO date string
  z.date(),          // output schema: Date object
  {
    decode: (isoString) => new Date(isoString), // ISO string → Date
    encode: (date) => date.toISOString(),       // Date → ISO string
  }
);

一个常规的 .parse() 操作执行前向变换。它调用编解码器的 decode 函数。

🌐 A regular .parse() operations performs the forward transform. It calls the codec's decode function.

stringToDate.parse("2024-01-15T10:30:00.000Z"); // => Date

你也可以选择使用顶层的 z.decode() 函数。与接受 unknown 输入的 .parse() 不同，z.decode() 期望一个强类型输入（在此示例中为 string）。

🌐 You can alternatively use the top-level z.decode() function. Unlike .parse() (which accepts unknown input), z.decode() expects a strongly-typed input (string in this example).

z.decode(stringToDate, "2024-01-15T10:30:00.000Z"); // => Date

要执行反向变换，使用逆变换：z.encode()。

🌐 To perform the reverse transform, use the inverse: z.encode().

z.encode(stringToDate, new Date("2024-01-15")); // => "2024-01-15T00:00:00.000Z"

有关更多信息，请参阅专用的 Codecs 页面。该页面包含常用编解码器的实现，你可以将其复制/粘贴到你的项目中：

🌐 Refer to the dedicated Codecs page for more information. That page contains implementations for commonly-needed codecs that you can copy/paste into your project:

• stringToNumber
• stringToInt
• stringToBigInt
• numberToBigInt
• isoDatetimeToDate
• epochSecondsToDate
• epochMillisToDate
• jsonCodec
• utf8ToBytes
• bytesToUtf8
• base64ToBytes
• base64urlToBytes
• hexToBytes
• stringToURL
• stringToHttpURL
• uriComponent
• stringToBoolean

管道

🌐 Pipes

模式可以串联成“管道”。当与转换结合使用时，管道尤其有用。

🌐 Schemas can be chained together into "pipes". Pipes are primarily useful when used in conjunction with Transforms.

const stringToLength = z.string().pipe(z.transform(val => val.length));
 
stringToLength.parse("hello"); // => 5

转换

🌐 Transforms

转换是一种特殊类型的模式，用于执行单向转换。它们不是验证输入，而是接受任何内容并对数据进行某种转换。要定义一个转换：

🌐 Transforms are a special kind of schema that perform a unidirectional transformation. Instead of validating input, they accept anything and perform some transformation on the data. To define a transform:

const castToString = z.transform((val) => String(val));
 
castToString.parse("asdf"); // => "asdf"
castToString.parse(123); // => "123"
castToString.parse(true); // => "true"

要在转换中执行验证逻辑，请使用 ctx。要报告验证问题，请将新问题推送到 ctx.issues（类似于 .check() API）。

🌐 To perform validation logic inside a transform, use ctx. To report a validation issue, push a new issue onto ctx.issues (similar to the .check() API).

const coercedInt = z.transform((val, ctx) => {
  try {
    const parsed = Number.parseInt(String(val));
    return parsed;
  } catch (e) {
    ctx.issues.push({
      code: "custom",
      message: "Not a number",
      input: val,
    });
 
    // this is a special constant with type `never`
    // returning it lets you exit the transform without impacting the inferred return type
    return z.NEVER;
  }
});

最常见的是，变换通常与 管道 一起使用。这种组合对于执行一些初步验证，然后将解析的数据转换为另一种形式非常有用。

🌐 Most commonly, transforms are used in conjunction with Pipes. This combination is useful for performing some initial validation, then transforming the parsed data into another form.

const stringToLength = z.string().pipe(z.transform(val => val.length));
 
stringToLength.parse("hello"); // => 5

.transform()

将一些模式传入转换是一种常见模式，因此 Zod 提供了一个方便的 .transform() 方法。

🌐 Piping some schema into a transform is a common pattern, so Zod provides a convenience .transform() method.

const stringToLength = z.string().transform(val => val.length); 

转换也可以是异步的：

🌐 Transforms can also be async:

const idToUser = z
  .string()
  .transform(async (id) => {
    // fetch user from database
    return db.getUserById(id); 
  });
 
const user = await idToUser.parseAsync("abc123");

.preprocess()

将一个变换传入另一个模式是另一个常见模式，因此 Zod 提供了一个方便的 z.preprocess() 函数。

🌐 Piping a transform into another schema is another common pattern, so Zod provides a convenience z.preprocess() function.

const coercedInt = z.preprocess((val) => {
  if (typeof val === "string") {
    return Number.parseInt(val);
  }
  return val;
}, z.int());

默认值

🌐 Defaults

要设置模式的默认值：

🌐 To set a default value for a schema:

const defaultTuna = z.string().default("tuna");
 
defaultTuna.parse(undefined); // => "tuna"

或者，你可以传递一个函数，每当需要生成默认值时，该函数都会重新执行：

🌐 Alternatively, you can pass a function which will be re-executed whenever a default value needs to be generated:

const randomDefault = z.number().default(Math.random);
 
randomDefault.parse(undefined);    // => 0.4413456736055323
randomDefault.parse(undefined);    // => 0.1871840107401901
randomDefault.parse(undefined);    // => 0.7223408162401552

预错误

🌐 Prefaults

在 Zod 中，设置 默认 值会短路解析过程。如果输入是 undefined，则会立即返回默认值。因此，默认值必须可以赋值给模式的 输出类型。

🌐 In Zod, setting a default value will short-circuit the parsing process. If the input is undefined, the default value is eagerly returned. As such, the default value must be assignable to the output type of the schema.

const schema = z.string().transform(val => val.length).default(0);
schema.parse(undefined); // => 0

有时，定义一个 预故障（"预解析默认"）值是有用的。如果输入是 undefined，将会解析预故障值。解析过程 不会 被短路。因此，预故障值必须可以分配给模式的 输入类型。

🌐 Sometimes, it's useful to define a prefault ("pre-parse default") value. If the input is undefined, the prefault value will be parsed instead. The parsing process is not short circuited. As such, the prefault value must be assignable to the input type of the schema.