Zod | Zod 中文网

zod/v4 包是 Zod 生态系统的 "flagship" 库。它在开发者体验和包大小之间取得了平衡，非常适合绝大多数应用。

¥The zod/v4 package is the "flagship" library of the Zod ecosystem. It strikes a balance between developer experience and bundle size that's ideal for the vast majority of applications.

如果你对包大小有非常严格的限制，请考虑使用 Zod Mini。

¥If you have uncommonly strict constraints around bundle size, consider Zod Mini.

Zod 旨在提供一个与 TypeScript 类型系统一对一映射的 Schema API。

¥Zod aims to provide a schema API that maps one-to-one to TypeScript's type system.

import { z } from "zod/v4";
 
const schema = z.object({
  name: z.string(),
  age: z.number().int().positive(),
  email: z.string().email(),
});

该 API 依靠方法提供一种简洁、可链接且支持自动补齐的方法来定义复杂类型。

¥The API relies on methods to provide a concise, chainable, autocomplete-friendly way to define complex types.

z.string()
  .min(5)
  .max(10)
  .toLowerCase();

所有模式都扩展了 z.ZodType 基类，而 z.ZodType 基类又从 zod/v4/core 扩展了 z.$ZodType。ZodType 的所有实例都实现了以下方法：

¥All schemas extend the z.ZodType base class, which in turn extends z.$ZodType from zod/v4/core. All instance of ZodType implement the following methods:

import { z } from "zod/v4";
 
const mySchema = z.string();
 
// parsing
mySchema.parse(data);
mySchema.safeParse(data);
mySchema.parseAsync(data);
mySchema.safeParseAsync(data);
 
 
// refinements
mySchema.refine(refinementFunc);
mySchema.superRefine(refinementFunc); // deprecated, use `.check()`
mySchema.overwrite(overwriteFunc);
 
// wrappers
mySchema.optional();
mySchema.nonoptional();
mySchema.nullable();
mySchema.nullish();
mySchema.default(defaultValue);
mySchema.array();
mySchema.or(otherSchema);
mySchema.transform(transformFunc);
mySchema.catch(catchValue);
mySchema.pipe(otherSchema);
mySchema.readonly();
 
// metadata and registries
mySchema.register(registry, metadata);
mySchema.describe(description);
mySchema.meta(metadata);
 
// utilities
mySchema.check(checkOrFunction);
mySchema.clone(def);
mySchema.brand<T>();
mySchema.isOptional(); // boolean
mySchema.isNullable(); // boolean