Zod 中文网

简介​

¥Introduction

Zod 是一个 TypeScript 优先的模式声明和验证库。我使用术语 "schema" 来广泛指代任何数据类型，从简单的 string 到复杂的嵌套对象。

¥Zod is a TypeScript-first schema declaration and validation library. I'm using the term "schema" to broadly refer to any data type, from a simple string to a complex nested object.

Zod 的设计尽可能对开发者友好。目标是消除重复的类型声明。使用 Zod，你只需声明一次验证器，Zod 就会自动推断静态 TypeScript 类型。将更简单的类型组合成复杂的数据结构很容易。

¥Zod is designed to be as developer-friendly as possible. The goal is to eliminate duplicative type declarations. With Zod, you declare a validator once and Zod will automatically infer the static TypeScript type. It's easy to compose simpler types into complex data structures.

其他一些很棒的方面：

¥Some other great aspects:

• 零依赖

  ¥Zero dependencies

• 适用于 Node.js 和所有现代浏览器

  ¥Works in Node.js and all modern browsers

• Tiny:8kb 最小化 + 压缩

  ¥Tiny: 8kb minified + zipped

• 不可变：方法（例如 .optional()）返回一个新实例

  ¥Immutable: methods (e.g. .optional()) return a new instance

• 简洁、可链式的界面

  ¥Concise, chainable interface

• 功能方法：解析，不验证

  ¥Functional approach: parse, don't validate

• 也适用于纯 JavaScript！你不需要使用 TypeScript。

  ¥Works with plain JavaScript too! You don't need to use TypeScript.

生态系统​

¥Ecosystem

越来越多的工具建立在 Zod 之上或原生支持 Zod！如果你已经在 Zod 之上构建了一个工具或库，请告诉我有关它的 在 Twitter 上 或 开始讨论。我会在下面添加它并发推文。

¥There are a growing number of tools that are built atop or support Zod natively! If you've built a tool or library on top of Zod, tell me about it on Twitter or start a Discussion. I'll add it below and tweet it out.

资源​

¥Resources

• 完整的 TypeScript Zod 教程 by @mattpocockuk

  ¥Total TypeScript Zod Tutorial by @mattpocockuk

• 修复 TypeScript 的盲点：运行时类型检查 by @jherr

  ¥Fixing TypeScript's Blindspot: Runtime Typechecking by @jherr

API 库​

¥API libraries

• tRPC：无需 GraphQL 即可构建端到端类型安全 API。

  ¥tRPC: Build end-to-end typesafe APIs without GraphQL.

• @anatine/zod-nestjs：在 NestJS 项目中使用 Zod 的辅助方法。

  ¥@anatine/zod-nestjs: Helper methods for using Zod in a NestJS project.

• zod-endpoints：使用 Zod 的契约优先严格类型端点。兼容 OpenAPI。

  ¥zod-endpoints: Contract-first strictly typed endpoints with Zod. OpenAPI compatible.

• zhttp：一个与 OpenAPI 兼容的、严格类型的 http 库，具有 Zod 输入和响应验证。

  ¥zhttp: An OpenAPI compatible, strictly typed http library with Zod input and response validation.

• domain-functions：使用可组合函数将你的业务逻辑与框架分离。使用 Zod 模式从头到尾进行一流的类型推断。

  ¥domain-functions: Decouple your business logic from your framework using composable functions. With first-class type inference from end to end powered by Zod schemas.

• @zodios/core：具有由 axios 和 zod 支持的运行时和编译时验证的 typescript API 客户端。

  ¥@zodios/core: A typescript API client with runtime and compile time validation backed by axios and zod.

• express-zod-api：使用 I/O 模式验证和自定义中间件构建基于 Express 的 API。

  ¥express-zod-api: Build Express-based APIs with I/O schema validation and custom middlewares.

• tapiduck：使用 Zod 和 Express 实现端到端类型安全 JSON API；有点像 tRPC，但更简单。

  ¥tapiduck: End-to-end typesafe JSON APIs with Zod and Express; a bit like tRPC, but simpler.

• koa-zod-router：使用 Zod 在 Koa 中创建具有 I/O 验证的类型安全路由。

  ¥koa-zod-router: Create typesafe routes in Koa with I/O validation using Zod.

• zod-sockets：Zod 驱动的 Socket.IO 微框架，具有 I/O 验证和内置 AsyncAPI 规范

  ¥zod-sockets: Zod-powered Socket.IO microframework with I/O validation and built-in AsyncAPI specs

表单集成​

¥Form integrations

• react-hook-form：React Hook Form 的第一方 Zod 解析器。

  ¥react-hook-form: A first-party Zod resolver for React Hook Form.

• zod-validation-error：从 ZodError 生成用户友好的错误消息。

  ¥zod-validation-error: Generate user-friendly error messages from ZodErrors.

• zod-formik-adapter：社区维护的 Zod Formik 适配器。

  ¥zod-formik-adapter: A community-maintained Formik adapter for Zod.

• react-zorm：使用 Zod 为 React 生成和验证独立 <form>。

  ¥react-zorm: Standalone <form> generation and validation for React using Zod.

• zodix：Remix 加载器和操作中的 FormData 和 URLSearchParams 的 Zod 实用程序。

  ¥zodix: Zod utilities for FormData and URLSearchParams in Remix loaders and actions.

• conform：用于逐步增强 HTML 表单的类型安全表单验证库。适用于 Remix 和 Next.js。

  ¥conform: A typesafe form validation library for progressive enhancement of HTML forms. Works with Remix and Next.js.

• remix-params-helper：简化 Zod 与 Remix 应用的标准 URLSearchParams 和 FormData 的集成。

  ¥remix-params-helper: Simplify integration of Zod with standard URLSearchParams and FormData for Remix apps.

• formik-validator-zod：兼容 Formik 的验证器库，可简化 Zod 与 Formik 的使用。

  ¥formik-validator-zod: Formik-compliant validator library that simplifies using Zod with Formik.

• zod-i18n-map：用于翻译 Zod 错误消息。

  ¥zod-i18n-map: Useful for translating Zod error messages.

• @modular-forms/solid：支持 Zod 验证的 SolidJS 模块化表单库。

  ¥@modular-forms/solid: Modular form library for SolidJS that supports Zod for validation.

• houseform：使用 Zod 进行验证的 React 表单库。

  ¥houseform: A React form library that uses Zod for validation.

• sveltekit-superforms：带有 Zod 验证的 SvelteKit 增强型表单库。

  ¥sveltekit-superforms: Supercharged form library for SvelteKit with Zod validation.

• mobx-zod-form：基于 MobX 和 Zod 的数据优先表单构建器。

  ¥mobx-zod-form: Data-first form builder based on MobX & Zod.

• @vee-validate/zod：带有 Zod 模式验证的 Vue.js 表单库。

  ¥@vee-validate/zod: Form library for Vue.js with Zod schema validation.

Zod 到 X​

¥Zod to X

• zod-to-ts：从 Zod 模式生成 TypeScript 定义。

  ¥zod-to-ts: Generate TypeScript definitions from Zod schemas.

• zod-to-json-schema：将你的 Zod 模式转换为 JSON 模式。

  ¥zod-to-json-schema: Convert your Zod schemas into JSON Schemas.

• @anatine/zod-openapi：将 Zod 模式转换为 OpenAPI v3.x SchemaObject。

  ¥@anatine/zod-openapi: Converts a Zod schema to an OpenAPI v3.x SchemaObject.

• zod-fast-check：从 Zod 模式生成 fast-check 任意值。

  ¥zod-fast-check: Generate fast-check arbitraries from Zod schemas.

• zod-dto：从 Zod 模式生成 Nest.js DTO。

  ¥zod-dto: Generate Nest.js DTOs from a Zod schema.

• fastify-type-provider-zod：从 Zod 模式创建 Fastify 类型提供程序。

  ¥fastify-type-provider-zod: Create Fastify type providers from Zod schemas.

• zod-to-openapi：从 Zod 生成完整的 OpenAPI（Swagger）文档，包括模式、端点和参数。

  ¥zod-to-openapi: Generate full OpenAPI (Swagger) docs from Zod, including schemas, endpoints & parameters.

• nestjs-graphql-zod：从 Zod 模式生成 NestJS GraphQL 模型类。提供与 Zod 模式配合使用的 GraphQL 方法装饰器。

  ¥nestjs-graphql-zod: Generates NestJS GraphQL model classes from Zod schemas. Provides GraphQL method decorators working with Zod schemas.

• zod-openapi：从 Zod 模式创建完整的 OpenAPI v3.x 文档。

  ¥zod-openapi: Create full OpenAPI v3.x documentation from Zod schemas.

• fastify-zod-openapi：Fastify 类型提供程序、验证、序列化和 @fastify/swagger 对 Zod 模式的支持。

  ¥fastify-zod-openapi: Fastify type provider, validation, serialization and @fastify/swagger support for Zod schemas.

• typeschema：用于模式验证的通用适配器。

  ¥typeschema: Universal adapter for schema validation.

X 到 Zod​

¥X to Zod

• ts-to-zod：将 TypeScript 定义转换为 Zod 模式。

  ¥ts-to-zod: Convert TypeScript definitions into Zod schemas.

• @runtyping/zod：从静态类型和 JSON 模式生成 Zod。

  ¥@runtyping/zod: Generate Zod from static types & JSON schema.

• json-schema-to-zod：将你的 JSON 模式 转换为 Zod 模式。在线演示。

  ¥json-schema-to-zod: Convert your JSON Schemas into Zod schemas. Live demo.

• json-to-zod：将 JSON 对象转换为 Zod 模式。在线演示。

  ¥json-to-zod: Convert JSON objects into Zod schemas. Live demo.

• graphql-codegen-typescript-validation-schema：GraphQL 代码生成器插件可从你的 GraphQL 模式生成表单验证模式。

  ¥graphql-codegen-typescript-validation-schema: GraphQL Code Generator plugin to generate form validation schema from your GraphQL schema.

• zod-prisma：从 Prisma 模式生成 Zod 模式。

  ¥zod-prisma: Generate Zod schemas from your Prisma schema.

• Supervillain：从你的 Go 结构生成 Zod 模式。

  ¥Supervillain: Generate Zod schemas from your Go structs.

• prisma-zod-generator：从 Prisma 模式中发出 Zod 模式。

  ¥prisma-zod-generator: Emit Zod schemas from your Prisma schema.

• drizzle-zod：从 Drizzle 模式中发出 Zod 模式。

  ¥drizzle-zod: Emit Zod schemas from your Drizzle schema.

• prisma-trpc-generator：使用 Zod 发出完全实现的 tRPC 路由及其验证模式。

  ¥prisma-trpc-generator: Emit fully implemented tRPC routers and their validation schemas using Zod.

• zod-prisma-types 从你的 Prisma 模型创建 Zod 类型。

  ¥zod-prisma-types Create Zod types from your Prisma models.

• quicktype：将 JSON 对象和 JSON 模式转换为 Zod 模式。

  ¥quicktype: Convert JSON objects and JSON schemas into Zod schemas.

• @sanity-typed/zod：从 健全性模式 生成 Zod 模式。

  ¥@sanity-typed/zod: Generate Zod Schemas from Sanity Schemas.

• java-to-zod：将 POJO 转换为 Zod 模式

  ¥java-to-zod: Convert POJOs to Zod schemas

• Orval：从 OpenAPI 模式生成 Zod 模式

  ¥Orval: Generate Zod schemas from OpenAPI schemas

• Kubb：从你的 OpenAPI 模式生成 SDK 和 Zod 模式

  ¥Kubb: Generate SDKs and Zod schemas from your OpenAPI schemas

模拟​

¥Mocking

• @anatine/zod-mock：从 Zod 模式生成模拟数据。由 faker.js 提供支持。

  ¥@anatine/zod-mock: Generate mock data from a Zod schema. Powered by faker.js.

• zod-mocking：从 Zod 模式生成模拟数据。

  ¥zod-mocking: Generate mock data from your Zod schemas.

• zod-fixture：使用你的 zod 模式以确定性方式自动生成不相关的测试装置。

  ¥zod-fixture: Use your zod schemas to automate the generation of non-relevant test fixtures in a deterministic way.

• zocker：从你的模式生成合理的模拟数据。

  ¥zocker: Generate plausible mock-data from your schemas.

• zodock 根据 Zod 模式生成模拟数据。

  ¥zodock Generate mock data based on Zod schemas.

• zod-schema-faker 从 Zod 模式生成模拟数据。由 @faker-js/faker 和 randexp.js 提供支持

  ¥zod-schema-faker Generates mock data from Zod schemas. Powered by @faker-js/faker and randexp.js

由 Zod 提供支持​

¥Powered by Zod

• freerstore：Firestore 成本优化器。

  ¥freerstore: Firestore cost optimizer.

• slonik：具有强大 Zod 集成的 Node.js Postgres 客户端。

  ¥slonik: Node.js Postgres client with strong Zod integration.

• soly：使用 zod 创建 CLI 应用。

  ¥soly: Create CLI applications with zod.

• pastel：使用 react、zod 和 ink 创建 CLI 应用。

  ¥pastel: Create CLI applications with react, zod, and ink.

• zod-xlsx：使用 Zod 模式的基于 xlsx 的资源验证器。

  ¥zod-xlsx: A xlsx based resource validator using Zod schemas.

• znv：使用 Zod 模式对 Node.js 进行类型安全环境解析和验证。

  ¥znv: Type-safe environment parsing and validation for Node.js with Zod schemas.

• zod-config：使用灵活的适配器跨多个源加载配置，确保 Zod 的类型安全。

  ¥zod-config: Load configurations across multiple sources with flexible adapters, ensuring type safety with Zod.

Zod 实用程序​

¥Utilities for Zod

• zod_utilz：Zod 的框架无关实用程序。

  ¥zod_utilz: Framework agnostic utilities for Zod.

• zod-playground：用于学习和测试 Zod 模式验证功能的工具。链接。

  ¥zod-playground: A tool for learning and testing Zod schema validation functionalities. Link.

• zod-sandbox：用于测试 zod 模式的受控环境。在线演示。

  ¥zod-sandbox: Controlled environment for testing zod schemas. Live demo.

• zod-dev：在生产中有条件地禁用 Zod 运行时解析。

  ¥zod-dev: Conditionally disables Zod runtime parsing in production.

• zod-accelerator：将 Zod 的吞吐量提高至约 100 倍。

  ¥zod-accelerator: Accelerates Zod's throughput up to ~100x.

安装​

¥Installation

要求​

¥Requirements

• TypeScript 4.5+！

• 你必须在 tsconfig.json 中启用 strict 模式。这是所有 TypeScript 项目的最佳实践。

  ¥You must enable strict mode in your tsconfig.json. This is a best practice for all TypeScript projects.

  // tsconfig.json
  {
    // ...
    "compilerOptions": {
      // ...
      "strict": true
    }
  }
  

来自 npm (Node/Bun)​

¥From npm (Node/Bun)

npm install zod       # npm
yarn add zod          # yarn
bun add zod           # bun
pnpm add zod          # pnpm

Zod 还在每次提交时发布一个预览版本。要安装预览版：

¥Zod also publishes a canary version on every commit. To install the canary:

npm install zod@canary       # npm
yarn add zod@canary          # yarn
bun add zod@canary           # bun
pnpm add zod@canary          # pnpm

来自 deno.land/x (Deno)​

¥From deno.land/x (Deno)

与 Node 不同，Deno 依赖于直接 URL 导入，而不是像 NPM 这样的包管理器。Zod 可在 deno.land/x 上使用。最新版本可以像这样导入：

¥Unlike Node, Deno relies on direct URL imports instead of a package manager like NPM. Zod is available on deno.land/x. The latest version can be imported like so:

import { z } from "https://deno.land/x/zod/mod.ts";

你还可以指定特定版本：

¥You can also specify a particular version:

import { z } from "https://deno.land/x/zod@v3.16.1/mod.ts";

本 README 的其余部分假定你正在使用 npm 并直接从 "zod" 包导入。

¥The rest of this README assumes you are using npm and importing directly from the "zod" package.

基本用法​

¥Basic usage

创建一个简单的字符串模式

¥Creating a simple string schema

import { z } from "zod";

// creating a schema for strings
const mySchema = z.string();

// parsing
mySchema.parse("tuna"); // => "tuna"
mySchema.parse(12); // => throws ZodError

// "safe" parsing (doesn't throw error if validation fails)
mySchema.safeParse("tuna"); // => { success: true; data: "tuna" }
mySchema.safeParse(12); // => { success: false; error: ZodError }

创建对象模式

¥Creating an object schema

import { z } from "zod";

const User = z.object({
  username: z.string(),
});

User.parse({ username: "Ludwig" });

// extract the inferred type
type User = z.infer<typeof User>;
// { username: string }

原始​

¥Primitives

import { z } from "zod";

// primitive values
z.string();
z.number();
z.bigint();
z.boolean();
z.date();
z.symbol();

// empty types
z.undefined();
z.null();
z.void(); // accepts undefined

// catch-all types
// allows any value
z.any();
z.unknown();

// never type
// allows no values
z.never();

原语强制​

¥Coercion for primitives

Zod 现在提供了一种更方便的方式来强制原始值。

¥Zod now provides a more convenient way to coerce primitive values.

const schema = z.coerce.string();
schema.parse("tuna"); // => "tuna"
schema.parse(12); // => "12"

在解析步骤中，输入通过 String() 函数传递，这是一个内置的 JavaScript，用于将数据强制转换为字符串。

¥During the parsing step, the input is passed through the String() function, which is a JavaScript built-in for coercing data into strings.

schema.parse(12); // => "12"
schema.parse(true); // => "true"
schema.parse(undefined); // => "undefined"
schema.parse(null); // => "null"

返回的模式是一个普通的 ZodString 实例，因此你可以使用所有字符串方法。

¥The returned schema is a normal ZodString instance so you can use all string methods.

z.coerce.string().email().min(5);

强制如何工作

¥How coercion works

所有原始类型都支持强制转换。Zod 使用内置构造函数强制所有输入：String(input)、Number(input)、new Date(input) 等。

¥All primitive types support coercion. Zod coerces all inputs using the built-in constructors: String(input), Number(input), new Date(input), etc.

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

注意 — z.coerce.boolean() 的布尔强制转换可能无法按预期工作。任何 truthy 值都强制转换为 true，任何 falsy 值都强制转换为 false。

¥Note — Boolean coercion with z.coerce.boolean() may not work how you expect. Any truthy value is coerced to true, and any falsy value is coerced to false.

const schema = z.coerce.boolean(); // Boolean(input)

schema.parse("tuna"); // => true
schema.parse("true"); // => true
schema.parse("false"); // => true
schema.parse(1); // => true
schema.parse([]); // => true

schema.parse(0); // => false
schema.parse(""); // => false
schema.parse(undefined); // => false
schema.parse(null); // => false

为了更好地控制强制逻辑，请考虑使用 z.preprocess 或 z.pipe()。

¥For more control over coercion logic, consider using z.preprocess or z.pipe().

字面量​

¥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); // bigint literal
const tru = z.literal(true);

const terrificSymbol = Symbol("terrific");
const terrific = z.literal(terrificSymbol);

// retrieve literal value
tuna.value; // "tuna"

目前 Zod 不支持日期字面量。如果你有此功能的用例，请提交问题。

¥Currently there is no support for Date literals in Zod. If you have a use case for this feature, please file an issue.

字符串​

¥Strings

Zod 包含一些字符串特定的验证。

¥Zod includes a handful of string-specific validations.

// validations
z.string().max(5);
z.string().min(5);
z.string().length(5);
z.string().email();
z.string().url();
z.string().emoji();
z.string().uuid();
z.string().nanoid();
z.string().cuid();
z.string().cuid2();
z.string().ulid();
z.string().regex(regex);
z.string().includes(string);
z.string().startsWith(string);
z.string().endsWith(string);
z.string().datetime(); // ISO 8601; by default only `Z` timezone allowed
z.string().ip(); // defaults to allow both IPv4 and IPv6

// transforms
z.string().trim(); // trim whitespace
z.string().toLowerCase(); // toLowerCase
z.string().toUpperCase(); // toUpperCase

// added in Zod 3.23
z.string().date(); // ISO date format (YYYY-MM-DD)
z.string().time(); // ISO time format (HH:mm:ss[.SSSSSS])
z.string().duration(); // ISO 8601 duration
z.string().base64();

查看 validator.js 以获取可与 改进 结合使用的许多其他有用的字符串验证函数。

¥Check out validator.js for a bunch of other useful string validation functions that can be used in conjunction with Refinements.

你可以在创建字符串模式时自定义一些常见错误消息。

¥You can customize some common error messages when creating a string schema.

const name = z.string({
  required_error: "Name is required",
  invalid_type_error: "Name must be a string",
});

使用验证方法时，可以传入附加参数以提供自定义错误消息。

¥When using validation methods, you can pass in an additional argument to provide a custom error message.

z.string().min(5, { message: "Must be 5 or more characters long" });
z.string().max(5, { message: "Must be 5 or fewer characters long" });
z.string().length(5, { message: "Must be exactly 5 characters long" });
z.string().email({ message: "Invalid email address" });
z.string().url({ message: "Invalid url" });
z.string().emoji({ message: "Contains non-emoji characters" });
z.string().uuid({ message: "Invalid UUID" });
z.string().includes("tuna", { message: "Must include tuna" });
z.string().startsWith("https://", { message: "Must provide secure URL" });
z.string().endsWith(".com", { message: "Only .com domains allowed" });
z.string().datetime({ message: "Invalid datetime string! Must be UTC." });
z.string().date({ message: "Invalid date string!" });
z.string().time({ message: "Invalid time string!" });
z.string().ip({ message: "Invalid IP address" });

日期时间​

¥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.string().datetime() 方法强制执行 ISO 8601；默认没有时区偏移和任意亚秒小数精度。

¥The z.string().datetime() method enforces ISO 8601; default is no timezone offsets and arbitrary sub-second decimal precision.

const datetime = z.string().datetime();

datetime.parse("2020-01-01T00:00:00Z"); // pass
datetime.parse("2020-01-01T00:00:00.123Z"); // pass
datetime.parse("2020-01-01T00:00:00.123456Z"); // pass (arbitrary precision)
datetime.parse("2020-01-01T00:00:00+02:00"); // fail (no offsets allowed)

可以通过将 offset 选项设置为 true 来允许时区偏移。

¥Timezone offsets can be allowed by setting the offset option to true.

const datetime = z.string().datetime({ offset: true });

datetime.parse("2020-01-01T00:00:00+02:00"); // pass
datetime.parse("2020-01-01T00:00:00.123+02:00"); // pass (millis optional)
datetime.parse("2020-01-01T00:00:00.123+0200"); // pass (millis optional)
datetime.parse("2020-01-01T00:00:00.123+02"); // pass (only offset hours)
datetime.parse("2020-01-01T00:00:00Z"); // pass (Z still supported)

你还可以限制允许的 precision。默认情况下，支持任意亚秒精度（但可选）。

¥You can additionally constrain the allowable precision. By default, arbitrary sub-second precision is supported (but optional).

const datetime = z.string().datetime({ precision: 3 });

datetime.parse("2020-01-01T00:00:00.123Z"); // pass
datetime.parse("2020-01-01T00:00:00Z"); // fail
datetime.parse("2020-01-01T00:00:00.123456Z"); // fail

日期​

¥Dates

Zod 3.23 中添加

¥Added in Zod 3.23

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

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

const date = z.string().date();

date.parse("2020-01-01"); // pass
date.parse("2020-1-1"); // fail
date.parse("2020-01-32"); // fail

时间​

¥Times

Zod 3.23 中添加

¥Added in Zod 3.23

z.string().time() 方法验证 HH:MM:SS[.s+] 格式的字符串。第二个可以包含任意十进制精度。它不允许任何类型的时区偏移。

¥The z.string().time() method validates strings in the format HH:MM:SS[.s+]. The second can include arbitrary decimal precision. It does not allow timezone offsets of any kind.

const time = z.string().time();

time.parse("00:00:00"); // pass
time.parse("09:52:31"); // pass
time.parse("23:59:59.9999999"); // pass (arbitrary precision)

time.parse("00:00:00.123Z"); // fail (no `Z` allowed)
time.parse("00:00:00.123+02:00"); // fail (no offsets allowed)

你可以设置 precision 选项来限制允许的小数精度。

¥You can set the precision option to constrain the allowable decimal precision.

const time = z.string().time({ precision: 3 });

time.parse("00:00:00.123"); // pass
time.parse("00:00:00.123456"); // fail
time.parse("00:00:00"); // fail

IP 地址​

¥IP addresses

z.string().ip() 方法默认验证 IPv4 和 IPv6。

¥The z.string().ip() method by default validate IPv4 and IPv6.

const ip = z.string().ip();

ip.parse("192.168.1.1"); // pass
ip.parse("84d5:51a0:9114:1855:4cfa:f2d7:1f12:7003"); // pass
ip.parse("84d5:51a0:9114:1855:4cfa:f2d7:1f12:192.168.1.1"); // pass

ip.parse("256.1.1.1"); // fail
ip.parse("84d5:51a0:9114:gggg:4cfa:f2d7:1f12:7003"); // fail

你还可以设置 IP version。

¥You can additionally set the IP version.

const ipv4 = z.string().ip({ version: "v4" });
ipv4.parse("84d5:51a0:9114:1855:4cfa:f2d7:1f12:7003"); // fail

const ipv6 = z.string().ip({ version: "v6" });
ipv6.parse("192.168.1.1"); // fail

数字​

¥Numbers

你可以在创建数字模式时自定义某些错误消息。

¥You can customize certain error messages when creating a number schema.

const age = z.number({
  required_error: "Age is required",
  invalid_type_error: "Age must be a number",
});

Zod 包含一些数字特定的验证。

¥Zod includes 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().int(); // value must be an integer

z.number().positive(); //     > 0
z.number().nonnegative(); //  >= 0
z.number().negative(); //     < 0
z.number().nonpositive(); //  <= 0

z.number().multipleOf(5); // Evenly divisible by 5. Alias .step(5)

z.number().finite(); // value must be finite, not Infinity or -Infinity
z.number().safe(); // value must be between Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER

或者，你可以传入第二个参数来提供自定义错误消息。

¥Optionally, you can pass in a second argument to provide a custom error message.

z.number().lte(5, { message: "this👏is👏too👏big" });

BigInts​

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(); // > 0n
z.bigint().nonnegative(); // >= 0n
z.bigint().negative(); // < 0n
z.bigint().nonpositive(); // <= 0n

z.bigint().multipleOf(5n); // Evenly divisible by 5n.

NaNs​

你可以在创建 nan 模式时自定义某些错误消息。

¥You can customize certain error messages when creating a nan schema.

const isNaN = z.nan({
  required_error: "isNaN is required",
  invalid_type_error: "isNaN must be 'not a number'",
});

布尔值​

¥Booleans

你可以在创建布尔模式时自定义某些错误消息。

¥You can customize certain error messages when creating a boolean schema.

const isActive = z.boolean({
  required_error: "isActive is required",
  invalid_type_error: "isActive must be a boolean",
});

日期​

¥Dates

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

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

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

你可以在创建日期模式时自定义某些错误消息。

¥You can customize certain error messages when creating a date schema.

const myDateSchema = z.date({
  required_error: "Please select a date and time",
  invalid_type_error: "That's not a date!",
});

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

¥Zod provides a handful of date-specific validations.

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

强制转换为日期

¥Coercion to Date

自 zod 3.20 起，使用 z.coerce.date() 将输入传递到 new Date(input)。

¥Since zod 3.20, use z.coerce.date() to pass the input through new Date(input).

const dateSchema = z.coerce.date();
type DateSchema = z.infer<typeof dateSchema>;
// type DateSchema = Date

/* valid dates */
console.log(dateSchema.safeParse("2023-01-10T00:00:00.000Z").success); // true
console.log(dateSchema.safeParse("2023-01-10").success); // true
console.log(dateSchema.safeParse("1/10/23").success); // true
console.log(dateSchema.safeParse(new Date("1/10/23")).success); // true

/* invalid dates */
console.log(dateSchema.safeParse("2023-13-10").success); // false
console.log(dateSchema.safeParse("0000-00-00").success); // false

对于较旧的 zod 版本，使用 z.preprocess 就像 在此线程中描述 一样。

¥For older zod versions, use z.preprocess like described in this thread.

Zod 枚举​

¥Zod enums

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

z.enum 是一种 Zod 原生方式，用于声明具有一组固定允许字符串值的模式。将值数组直接传递到 z.enum()。或者，使用 as const 将枚举值定义为字符串元组。有关详细信息，请参阅 const 断言文档。

¥z.enum is a Zod-native way to declare a schema with a fixed set of allowable string values. Pass the array of values directly into z.enum(). Alternatively, use as const to define your enum values as a tuple of strings. See the const assertion docs for details.

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

这是不允许的，因为 Zod 无法推断每个元素的确切值。

¥This is not allowed, since Zod isn't able to infer the exact values of each element.

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

.enum

要使用 Zod 枚举实现自动补齐，请使用模式的 .enum 属性：

¥To get autocompletion with a Zod enum, use the .enum property of your schema:

FishEnum.enum.Salmon; // => autocompletes

FishEnum.enum;
/*
=> {
  Salmon: "Salmon",
  Tuna: "Tuna",
  Trout: "Trout",
}
*/

你还可以使用 .options 属性以元组形式检索选项列表：

¥You can also retrieve the list of options as a tuple with the .options property:

FishEnum.options; // ["Salmon", "Tuna", "Trout"];

.exclude/.extract()

你可以使用 .exclude 和 .extract 方法创建 Zod 枚举的子集。

¥You can create subsets of a Zod enum with the .exclude and .extract methods.

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

原生枚举​

¥Native enums

Zod 枚举是定义和验证枚举的推荐方法。但如果你需要针对第三方库中的枚举进行验证（或者你不想重写现有的枚举），则可以使用 z.nativeEnum()。

¥Zod enums are the recommended approach to defining and validating enums. But if you need to validate against an enum from a third-party library (or you don't want to rewrite your existing enums) you can use z.nativeEnum().

数字枚举

¥Numeric enums

enum Fruits {
  Apple,
  Banana,
}

const FruitEnum = z.nativeEnum(Fruits);
type FruitEnum = z.infer<typeof FruitEnum>; // Fruits

FruitEnum.parse(Fruits.Apple); // passes
FruitEnum.parse(Fruits.Banana); // passes
FruitEnum.parse(0); // passes
FruitEnum.parse(1); // passes
FruitEnum.parse(3); // fails

字符串枚举

¥String enums

enum Fruits {
  Apple = "apple",
  Banana = "banana",
  Cantaloupe, // you can mix numerical and string enums
}

const FruitEnum = z.nativeEnum(Fruits);
type FruitEnum = z.infer<typeof FruitEnum>; // Fruits

FruitEnum.parse(Fruits.Apple); // passes
FruitEnum.parse(Fruits.Cantaloupe); // passes
FruitEnum.parse("apple"); // passes
FruitEnum.parse("banana"); // passes
FruitEnum.parse(0); // passes
FruitEnum.parse("Cantaloupe"); // fails

Const 枚举

¥Const enums

.nativeEnum() 函数也适用于 as const 对象。⚠️ as const 需要 TypeScript 3.4+！

¥The .nativeEnum() function works for as const objects as well. ⚠️ as const requires TypeScript 3.4+!

const Fruits = {
  Apple: "apple",
  Banana: "banana",
  Cantaloupe: 3,
} as const;

const FruitEnum = z.nativeEnum(Fruits);
type FruitEnum = z.infer<typeof FruitEnum>; // "apple" | "banana" | 3

FruitEnum.parse("apple"); // passes
FruitEnum.parse("banana"); // passes
FruitEnum.parse(3); // passes
FruitEnum.parse("Cantaloupe"); // fails

你可以使用 .enum 属性访问底层对象：

¥You can access the underlying object with the .enum property:

FruitEnum.enum.Apple; // "apple"

可选项​

¥Optionals

你可以使用 z.optional() 使任何模式成为可选的。这将模式封装在 ZodOptional 实例中并返回结果。

¥You can make any schema optional with z.optional(). This wraps the schema in a ZodOptional instance and returns the result.

const schema = z.optional(z.string());

schema.parse(undefined); // => returns undefined
type A = z.infer<typeof schema>; // string | undefined

为方便起见，你还可以在现有模式上调用 .optional() 方法。

¥For convenience, you can also call the .optional() method on an existing schema.

const user = z.object({
  username: z.string().optional(),
});
type C = z.infer<typeof user>; // { username?: string | undefined };

你可以使用 .unwrap() 从 ZodOptional 实例中提取封装的模式。

¥You can extract the wrapped schema from a ZodOptional instance with .unwrap().

const stringSchema = z.string();
const optionalString = stringSchema.optional();
optionalString.unwrap() === stringSchema; // true

可空值​

¥Nullables

类似地，你可以使用 z.nullable() 创建可空类型。

¥Similarly, you can create nullable types with z.nullable().

const nullableString = z.nullable(z.string());
nullableString.parse("asdf"); // => "asdf"
nullableString.parse(null); // => null

或者使用 .nullable() 方法。

¥Or use the .nullable() method.

const E = z.string().nullable(); // equivalent to nullableString
type E = z.infer<typeof E>; // string | null

使用 .unwrap() 提取内部模式。

¥Extract the inner schema with .unwrap().

const stringSchema = z.string();
const nullableString = stringSchema.nullable();
nullableString.unwrap() === stringSchema; // true

对象​

¥Objects

// all properties are required by default
const Dog = z.object({
  name: z.string(),
  age: z.number(),
});

// extract the inferred type like this
type Dog = z.infer<typeof Dog>;

// equivalent to:
type Dog = {
  name: string;
  age: number;
};

.shape​

使用 .shape 访问特定键的模式。

¥Use .shape to access the schemas for a particular key.

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

.keyof​

使用 .keyof 从对象模式的键创建 ZodEnum 模式。

¥Use .keyof to create a ZodEnum schema from the keys of an object schema.

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

.extend​

你可以使用 .extend 方法向对象模式添加其他字段。

¥You can add additional fields to an object schema with the .extend method.

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

你可以使用 .extend 覆盖字段！小心使用这种力量！

¥You can use .extend to overwrite fields! Be careful with this power!

.merge​

相当于 A.extend(B.shape)。

¥Equivalent to A.extend(B.shape).

const BaseTeacher = z.object({ students: z.array(z.string()) });
const HasID = z.object({ id: z.string() });

const Teacher = BaseTeacher.merge(HasID);
type Teacher = z.infer<typeof Teacher>; // => { students: string[], id: string }

如果两个模式共享密钥，则 B 的属性将覆盖 A 的属性。返回的模式还继承了 "unknownKeys" 策略（strip/strict/passthrough）和 B 的 catchall 模式。

¥If the two schemas share keys, the properties of B overrides the property of A. The returned schema also inherits the "unknownKeys" policy (strip/strict/passthrough) and the catchall schema of B.

.pick/.omit​

受 TypeScript 内置 Pick 和 Omit 工具类型的启发，所有 Zod 对象模式都有返回修改版本的 .pick 和 .omit 方法。考虑此 Recipe 模式：

¥Inspired by TypeScript's built-in Pick and Omit utility types, all Zod object schemas have .pick and .omit methods that return a modified version. Consider this Recipe schema:

const Recipe = z.object({
  id: z.string(),
  name: z.string(),
  ingredients: z.array(z.string()),
});

要仅保留某些键，请使用 .pick。

¥To only keep certain keys, use .pick .

const JustTheName = Recipe.pick({ name: true });
type JustTheName = z.infer<typeof JustTheName>;
// => { name: string }

要删除某些键，请使用 .omit。

¥To remove certain keys, use .omit .

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

type NoIDRecipe = z.infer<typeof NoIDRecipe>;
// => { name: string, ingredients: string[] }

.partial​

受内置 TypeScript 工具类型 部分 的启发，.partial 方法使所有属性都成为可选的。

¥Inspired by the built-in TypeScript utility type Partial, the .partial method makes all properties optional.

从这个对象开始：

¥Starting from this object:

const user = z.object({
  email: z.string(),
  username: z.string(),
});
// { email: string; username: string }

我们可以创建部分版本：

¥We can create a partial version:

const partialUser = user.partial();
// { email?: string | undefined; username?: string | undefined }

你还可以指定使哪些属性成为可选：

¥You can also specify which properties to make optional:

const optionalEmail = user.partial({
  email: true,
});
/*
{
  email?: string | undefined;
  username: string
}
*/

.deepPartial​

.partial 方法很浅 — 它只应用一个深度级别。还有一个 "deep" 版本：

¥The .partial method is shallow — it only applies one level deep. There is also a "deep" version:

const user = z.object({
  username: z.string(),
  location: z.object({
    latitude: z.number(),
    longitude: z.number(),
  }),
  strings: z.array(z.object({ value: z.string() })),
});

const deepPartialUser = user.deepPartial();

/*
{
  username?: string | undefined,
  location?: {
    latitude?: number | undefined;
    longitude?: number | undefined;
  } | undefined,
  strings?: { value?: string}[]
}
*/

重要限制：深层部分仅在对象、数组和元组的层次结构中按预期工作。

¥Important limitation: deep partials only work as expected in hierarchies of objects, arrays, and tuples.

.required​

与 .partial 方法相反，.required 方法使所有属性成为必需。

¥Contrary to the .partial method, the .required method makes all properties required.

从这个对象开始：

¥Starting from this object:

const user = z
  .object({
    email: z.string(),
    username: z.string(),
  })
  .partial();
// { email?: string | undefined; username?: string | undefined }

我们可以创建必需版本：

¥We can create a required version:

const requiredUser = user.required();
// { email: string; username: string }

你还可以指定哪些属性是必需的：

¥You can also specify which properties to make required:

const requiredEmail = user.required({
  email: true,
});
/*
{
  email: string;
  username?: string | undefined;
}
*/

.passthrough​

默认情况下，Zod 对象模式会在解析过程中删除无法识别的键。

¥By default Zod object schemas strip out unrecognized keys during parsing.

const person = z.object({
  name: z.string(),
});

person.parse({
  name: "bob dylan",
  extraKey: 61,
});
// => { name: "bob dylan" }
// extraKey has been stripped

相反，如果你想传递未知键，请使用 .passthrough() 。

¥Instead, if you want to pass through unknown keys, use .passthrough() .

person.passthrough().parse({
  name: "bob dylan",
  extraKey: 61,
});
// => { name: "bob dylan", extraKey: 61 }

.strict​

默认情况下，Zod 对象模式会在解析过程中删除无法识别的键。你可以使用 .strict() 禁止未知键。如果输入中有任何未知键，Zod 将抛出错误。

¥By default Zod object schemas strip out unrecognized keys during parsing. You can disallow unknown keys with .strict() . If there are any unknown keys in the input, Zod will throw an error.

const person = z
  .object({
    name: z.string(),
  })
  .strict();

person.parse({
  name: "bob dylan",
  extraKey: 61,
});
// => throws ZodError

.strip​

你可以使用 .strip 方法将对象模式重置为默认行为（剥离无法识别的键）。

¥You can use the .strip method to reset an object schema to the default behavior (stripping unrecognized keys).

.catchall​

你可以将 "catchall" 模式传递到对象模式中。所有未知键都将根据它进行验证。

¥You can pass a "catchall" schema into an object schema. All unknown keys will be validated against it.

const person = z
  .object({
    name: z.string(),
  })
  .catchall(z.number());

person.parse({
  name: "bob dylan",
  validExtraKey: 61, // works fine
});

person.parse({
  name: "bob dylan",
  validExtraKey: false, // fails
});
// => throws ZodError

使用 .catchall() 可避免 .passthrough()、.strip() 或 .strict()。现在所有键都被视为 "known"。

¥Using .catchall() obviates .passthrough() , .strip() , or .strict(). All keys are now considered "known".

数组​

¥Arrays

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

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

小心使用 .array() 方法。它返回一个新的 ZodArray 实例。这意味着调用方法的顺序很重要。例如：

¥Be careful with the .array() method. It returns a new ZodArray instance. This means the order in which you call methods matters. For instance:

z.string().optional().array(); // (string | undefined)[]
z.string().array().optional(); // string[] | undefined

.element​

使用 .element 访问数组元素的模式。

¥Use .element to access the schema for an element of the array.

stringArray.element; // => string schema

.nonempty​

如果你想确保数组至少包含一个元素，请使用 .nonempty()。

¥If you want to ensure that an array contains at least one element, use .nonempty().

const nonEmptyStrings = z.string().array().nonempty();
// the inferred type is now
// [string, ...string[]]

nonEmptyStrings.parse([]); // throws: "Array cannot be empty"
nonEmptyStrings.parse(["Ariana Grande"]); // passes

你可以选择指定自定义错误消息：

¥You can optionally specify a custom error message:

// optional custom error message
const nonEmptyStrings = z.string().array().nonempty({
  message: "Can't be empty!",
});

.min/.max/.length​

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

与 .nonempty() 不同，这些方法不会更改推断的类型。

¥Unlike .nonempty() these methods do not change the inferred type.

元组​

¥Tuples

与数组不同，元组具有固定数量的元素，并且每个元素可以具有不同的类型。

¥Unlike arrays, tuples have a fixed number of elements and each element can have a different type.

const athleteSchema = z.tuple([
  z.string(), // name
  z.number(), // jersey number
  z.object({
    pointsScored: z.number(),
  }), // statistics
]);

type Athlete = z.infer<typeof athleteSchema>;
// type Athlete = [string, number, { pointsScored: number }]

可以使用 .rest 方法添加可变参数 ("rest") 参数。

¥A variadic ("rest") argument can be added with the .rest method.

const variadicTuple = z.tuple([z.string()]).rest(z.number());
const result = variadicTuple.parse(["hello", 1, 2, 3]);
// => [string, ...number[]];

联合​

¥Unions

Zod 包含一个内置的 z.union 方法，用于组成 "OR" 类型。

¥Zod includes a built-in z.union method for composing "OR" types.

const stringOrNumber = z.union([z.string(), z.number()]);

stringOrNumber.parse("foo"); // passes
stringOrNumber.parse(14); // passes

Zod 将按顺序针对每个 "options" 测试输入，并返回第一个成功验证的值。

¥Zod will test the input against each of the "options" in order and return the first value that validates successfully.

为了方便起见，你还可以使用 .or 方法：

¥For convenience, you can also use the .or method:

const stringOrNumber = z.string().or(z.number());

可选字符串验证：

¥Optional string validation:

要验证可选的表单输入，你可以将所需的字符串验证与空字符串 literal 联合。

¥To validate an optional form input, you can union the desired string validation with an empty string literal.

此示例验证可选的输入，但需要包含 有效 URL：

¥This example validates an input that is optional but needs to contain a valid URL:

const optionalUrl = z.union([z.string().url().nullish(), z.literal("")]);

console.log(optionalUrl.safeParse(undefined).success); // true
console.log(optionalUrl.safeParse(null).success); // true
console.log(optionalUrl.safeParse("").success); // true
console.log(optionalUrl.safeParse("https://zod.dev").success); // true
console.log(optionalUrl.safeParse("not a valid url").success); // false

可区分联合​

¥Discriminated unions

可区分联合是共享特定键的对象模式的联合。

¥A discriminated union is a union of object schemas that all share a particular key.

type MyUnion =
  | { status: "success"; data: string }
  | { status: "failed"; error: Error };

此类联合可以用 z.discriminatedUnion 方法表示。这可以实现更快的评估，因为 Zod 可以检查鉴别器键（上例中的 status）来确定应使用哪个模式来解析输入。这使得解析更有效率，并让 Zod 报告更友好的错误。

¥Such unions can be represented with the z.discriminatedUnion method. This enables faster evaluation, because Zod can check the discriminator key (status in the example above) to determine which schema should be used to parse the input. This makes parsing more efficient and lets Zod report friendlier errors.

使用基本联合方法，将针对每个提供的 "options" 测试输入，如果无效，所有 "options" 的问题都会显示在 zod 错误中。另一方面，可区分联合允许只选择其中一个 "options"，对其进行测试，并仅显示与此 "option" 相关的问题。

¥With the basic union method, the input is tested against each of the provided "options", and in the case of invalidity, issues for all the "options" are shown in the zod error. On the other hand, the discriminated union allows for selecting just one of the "options", testing against it, and showing only the issues related to this "option".

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

myUnion.parse({ status: "success", data: "yippie ki yay" });

你可以使用 .options 属性提取对模式数组的引用。

¥You can extract a reference to the array of schemas with the .options property.

myUnion.options; // [ZodObject<...>, ZodObject<...>]

要合并两个或多个可区分联合，请使用带有解构的 .options。

¥To merge two or more discriminated unions, use .options with destructuring.

const A = z.discriminatedUnion("status", [
  /* options */
]);
const B = z.discriminatedUnion("status", [
  /* options */
]);

const AB = z.discriminatedUnion("status", [...A.options, ...B.options]);

记录​

¥Records

记录模式用于验证 Record<string, number> 等类型。这对于按 ID 存储或缓存项目特别有用。

¥Record schemas are used to validate types such as Record<string, number>. This is particularly useful for storing or caching items by ID.

const User = z.object({ name: z.string() });

const UserStore = z.record(z.string(), User);
type UserStore = z.infer<typeof UserStore>;
// => Record<string, { name: string }>

模式和推断类型可以像这样使用：

¥The schema and inferred type can be used like so:

const userStore: UserStore = {};

userStore["77d2586b-9e8e-4ecf-8b21-ea7e0530eadd"] = {
  name: "Carlotta",
}; // passes

userStore["77d2586b-9e8e-4ecf-8b21-ea7e0530eadd"] = {
  whatever: "Ice cream sundae",
}; // TypeError

关于数字键的说明

¥A note on numerical keys

虽然 z.record(keyType, valueType) 能够接受数字键类型，并且 TypeScript 的内置记录类型是 Record<KeyType, ValueType>，但很难在 Zod 中表示 TypeScript 类型 Record<number, any>。

¥While z.record(keyType, valueType) is able to accept numerical key types and TypeScript's built-in Record type is Record<KeyType, ValueType>, it's hard to represent the TypeScript type Record<number, any> in Zod.

事实证明，TypeScript 围绕 [k: number] 的行为有点不直观：

¥As it turns out, TypeScript's behavior surrounding [k: number] is a little unintuitive:

const testMap: { [k: number]: string } = {
  1: "one",
};

for (const key in testMap) {
  console.log(`${key}: ${typeof key}`);
}
// prints: `1: string`