Zod | Zod 中文网

zod/v4 包是 Zod 生态系统的“旗舰”库。它在开发者体验和打包体积之间取得了平衡，对于绝大多数应用来说非常理想。

🌐 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。

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

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

import * as z from "zod";
 
const schema = z.object({
  name: z.string(),
  age: z.number().int().positive(),
  email: z.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 * as z from "zod";
 
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