Zod TypeScript 模式验证库：运行时数据验证与静态类型推断

zod by secondsky/claude-skills

199 周安装量

101 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/secondsky/claude-skills --skill zod

开发 TypeScript 代码质量

🇨🇳中文介绍

Zod：TypeScript 优先的模式验证

概述

Zod 是一个 TypeScript 优先的验证库，使开发者能够在运行时定义模式以验证数据，同时自动推断静态 TypeScript 类型。Zod 零依赖，核心包大小仅 2kb（gzip 压缩），提供不可变的、可组合的验证以及全面的错误处理。

安装

bun add zod
# 或
bun add zod
# 或
bun add zod
# 或
yarn add zod

要求：

TypeScript v5.5+，且 tsconfig.json 中设置 "strict": true
Zod 4.x (4.1.12+)

重要提示：此技能文档记录的是 Zod 4.x 功能。以下 API 需要 Zod 4，在 Zod 3.x 中不可用：

z.codec() - 双向转换
z.iso.date(), z.iso.time(), z.iso.datetime(), - ISO 格式验证器

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

从 Zod v3 迁移到 v4

加载 references/migration-guide.md 以获取完整的 v3 到 v4 迁移文档。

Zod v4 引入了破坏性变更以获得更好的性能：

错误自定义：使用统一的 error 参数（替代 message, invalid_type_error, required_error）
数字验证：更严格 - 拒绝 Infinity 和不安全的整数
字符串格式：现在作为顶级函数（z.email() 对比 z.string().email()）
对象默认值：即使在可选字段中也会应用
已弃用的 API：使用 .extend()（而非 .merge()），z.treeifyError()（而非 error.format()）
函数验证：使用 .implement() 方法
UUID 验证：更严格的 RFC 9562/4122 合规性

→ 加载 references/migration-guide.md 以获取： 完整的破坏性变更、迁移清单、渐进式迁移策略、回滚说明

import { z } from "zod";

// 定义模式
const UserSchema = z.object({
  username: z.string(),
  age: z.number().int().positive(),
  email: z.string().email(),
});

// 推断 TypeScript 类型
type User = z.infer<typeof UserSchema>;

// 验证数据（出错时抛出异常）
const user = UserSchema.parse(data);

// 验证数据（返回结果对象）
const result = UserSchema.safeParse(data);
if (result.success) {
  console.log(result.data); // 已类型化！
} else {
  console.error(result.error); // ZodError
}

根据错误处理需求使用适当的解析方法：

.parse(data) - 输入无效时抛出 ZodError；成功时返回强类型数据
.safeParse(data) - 返回 { success: true, data } 或 { success: false, error }（不抛出异常）
.parseAsync(data) - 用于包含异步细化/转换的模式
.safeParseAsync(data) - 不抛出异常的异步版本

最佳实践：使用 .safeParse() 以避免 try-catch 块，并利用可辨识联合类型。

z.string()                    // 基本字符串
z.string().min(5)            // 最小长度
z.string().max(100)          // 最大长度
z.string().length(10)        // 精确长度
z.string().email()           // 邮箱验证
z.string().url()             // URL 验证
z.string().uuid()            // UUID 格式
z.string().regex(/^\d+$/)    // 自定义模式
z.string().startsWith("pre") // 前缀检查
z.string().endsWith("suf")   // 后缀检查
z.string().trim()            // 自动修剪空白字符
z.string().toLowerCase()     // 自动转为小写
z.string().toUpperCase()     // 自动转为大写

// ISO 格式（Zod 4+）
z.iso.date()                 // YYYY-MM-DD
z.iso.time()                 // HH:MM:SS
z.iso.datetime()             // ISO 8601 日期时间
z.iso.duration()             // ISO 8601 持续时间

// 网络格式
z.ipv4()                     // IPv4 地址
z.ipv6()                     // IPv6 地址
z.cidrv4()                   // IPv4 CIDR 表示法
z.cidrv6()                   // IPv6 CIDR 表示法

// 其他格式
z.jwt()                      // JWT 令牌
z.nanoid()                   // Nanoid
z.cuid()                     // CUID
z.cuid2()                    // CUID2
z.ulid()                     // ULID
z.base64()                   // Base64 编码
z.hex()                      // 十六进制

z.number()                   // 基本数字
z.number().int()             // 仅整数
z.number().positive()        // > 0
z.number().nonnegative()     // >= 0
z.number().negative()        // < 0
z.number().nonpositive()     // <= 0
z.number().min(0)            // 最小值
z.number().max(100)          // 最大值
z.number().gt(0)             // 大于
z.number().gte(0)            // 大于或等于
z.number().lt(100)           // 小于
z.number().lte(100)          // 小于或等于
z.number().multipleOf(5)     // 必须是 5 的倍数
z.int()                      // z.number().int() 的简写
z.int32()                    // 32 位整数
z.nan()                      // NaN 值

强制转换（类型转换）

z.coerce.string()            // 转换为字符串
z.coerce.number()            // 转换为数字
z.coerce.boolean()           // 转换为布尔值
z.coerce.bigint()            // 转换为 bigint
z.coerce.date()              // 转换为 Date

// 示例：解析查询参数
const QuerySchema = z.object({
  page: z.coerce.number().int().positive(),
  limit: z.coerce.number().int().max(100).default(10),
});

// "?page=5&limit=20" -> { page: 5, limit: 20 }

z.boolean()                  // 布尔值
z.date()                     // Date 对象
z.date().min(new Date("2020-01-01"))
z.date().max(new Date("2030-12-31"))
z.bigint()                   // BigInt
z.symbol()                   // Symbol
z.null()                     // Null
z.undefined()                // Undefined
z.void()                     // Void (undefined)

const PersonSchema = z.object({
  name: z.string(),
  age: z.number(),
  address: z.object({
    street: z.string(),
    city: z.string(),
    country: z.string(),
  }),
});

type Person = z.infer<typeof PersonSchema>;

// 对象方法
PersonSchema.shape                 // 访问形状
PersonSchema.keyof()              // 获取键的联合类型
PersonSchema.extend({ role: z.string() })  // 添加字段
PersonSchema.pick({ name: true }) // 选取特定字段
PersonSchema.omit({ age: true })  // 省略字段
PersonSchema.partial()            // 使所有字段可选
PersonSchema.required()           // 使所有字段必填
PersonSchema.deepPartial()        // 递归可选

// 严格对象 vs 宽松对象
z.strictObject({ ... })           // 不允许额外键（抛出异常）
z.object({ ... })                 // 剥离额外键（默认）
z.looseObject({ ... })            // 允许额外键

z.array(z.string())              // 字符串数组
z.array(z.number()).min(1)       // 至少 1 个元素
z.array(z.number()).max(10)      // 最多 10 个元素
z.array(z.number()).length(5)    // 恰好 5 个元素
z.array(z.number()).nonempty()   // 至少 1 个元素

// 嵌套数组
z.array(z.array(z.number()))     // number[][]

z.tuple([z.string(), z.number()]) // [string, number]
z.tuple([z.string(), z.number()]).rest(z.boolean()) // [string, number, ...boolean[]]

// 枚举
const RoleEnum = z.enum(["admin", "user", "guest"]);
type Role = z.infer<typeof RoleEnum>; // "admin" | "user" | "guest"

// 字面量值
z.literal("exact_value")
z.literal(42)
z.literal(true)

// 原生 TypeScript 枚举
enum Fruits {
  Apple,
  Banana,
}
z.nativeEnum(Fruits)

// 枚举方法
RoleEnum.enum.admin              // "admin"
RoleEnum.exclude(["guest"])      // 排除值
RoleEnum.extract(["admin", "user"]) // 仅包含

// 基本联合类型
z.union([z.string(), z.number()])

// 可辨识联合类型（更好的性能和类型推断）
const ResponseSchema = z.discriminatedUnion("status", [
  z.object({ status: z.literal("success"), data: z.any() }),
  z.object({ status: z.literal("error"), message: z.string() }),
]);

type Response = z.infer<typeof ResponseSchema>;
// { status: "success", data: any } | { status: "error", message: string }

const BaseSchema = z.object({ id: z.string() });
const ExtendedSchema = z.object({ name: z.string() });

const Combined = z.intersection(BaseSchema, ExtendedSchema);
// 等价于：z.object({ id: z.string(), name: z.string() })

// 记录：具有类型化键和值的对象
z.record(z.string())             // { [key: string]: string }
z.record(z.string(), z.number()) // { [key: string]: number }

// 部分记录（某些键可选）
z.partialRecord(z.enum(["a", "b"]), z.string())

// 映射
z.map(z.string(), z.number())    // Map<string, number>
z.set(z.string())                // Set<string>

加载 references/advanced-patterns.md 以获取完整的高级验证和转换模式。

细化（自定义验证）：

z.string().refine((val) => val.length >= 8, "Too short");
z.object({ password, confirmPassword }).superRefine((data, ctx) => { /* ... */ });

转换（修改数据）：

z.string().transform((val) => val.trim());
z.string().pipe(z.coerce.number());

编解码器（双向转换 - v4.1 新增）：

const DateCodec = z.codec(
  z.iso.datetime(),
  z.date(),
  {
    decode: (str) => new Date(str),
    encode: (date) => date.toISOString(),
  }
);

const CategorySchema: z.ZodType<Category> = z.lazy(() =>
  z.object({ name: z.string(), subcategories: z.array(CategorySchema) })
);

可选/可空：

z.string().optional()            // string | undefined
z.string().nullable()            // string | null
z.string().default("default")    // 如果未定义则提供默认值

只读和品牌：

z.object({ ... }).readonly()     // 只读属性
z.string().brand<"UserId">()     // 名义类型

→ 加载 references/advanced-patterns.md 以获取： 完整的细化模式、异步验证、编解码器示例、可组合模式、条件验证、性能优化

加载 references/error-handling.md 以获取完整的错误格式化和自定义指南。

错误格式化方法：

// 用于表单
const { fieldErrors } = z.flattenError(error);

// 用于嵌套数据
const tree = z.treeifyError(error);
const nameError = tree.properties?.user?.properties?.name?.errors?.[0];

// 用于调试
console.log(z.prettifyError(error));

自定义错误消息（三个级别）：

// 1. 模式级别（最高优先级）
z.string({ error: "Custom message" });
z.string().min(5, "Too short");

// 2. 每次解析级别
schema.parse(data, { error: (issue) => ({ message: "..." }) });

// 3. 全局级别
z.config({ customError: (issue) => ({ message: "..." }) });

本地化（40+ 种语言）：

z.config(z.locales.es());  // 西班牙语
z.config(z.locales.fr());  // 法语

→ 加载 references/error-handling.md 以获取： 完整的错误格式化示例、自定义错误模式、本地化设置、错误代码参考

加载 references/type-inference.md 以获取完整的类型推断和元数据文档。

基本类型推断：

const UserSchema = z.object({ name: z.string() });
type User = z.infer<typeof UserSchema>; // { name: string }

输入 vs 输出（用于转换）：

const TransformSchema = z.string().transform((s) => s.length);
type Input = z.input<typeof TransformSchema>;   // string
type Output = z.output<typeof TransformSchema>; // number

JSON Schema 转换：

const jsonSchema = z.toJSONSchema(UserSchema, {
  target: "openapi-3.0",
  metadata: true,
});

// 添加元数据
const EmailSchema = z.string().email().meta({
  title: "Email Address",
  description: "User's email address",
});

// 创建自定义注册表
const formRegistry = z.registry<FormFieldMeta>();

→ 加载 references/type-inference.md 以获取： 完整的类型推断模式、JSON Schema 选项、元数据系统、自定义注册表、品牌类型

验证函数的输入和输出：

const AddFunction = z.function()
  .args(z.number(), z.number())  // 参数
  .returns(z.number());           // 返回类型

// 实现类型化函数
const add = AddFunction.implement((a, b) => {
  return a + b; // 类型检查！
});

// 异步函数
const FetchFunction = z.function()
  .args(z.string())
  .returns(z.promise(z.object({ data: z.any() })))
  .implementAsync(async (url) => {
    const response = await fetch(url);
    return response.json();
  });

const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "production", "test"]),
  DATABASE_URL: z.string().url(),
  PORT: z.coerce.number().int().positive().default(3000),
  API_KEY: z.string().min(32),
});

// 在启动时验证
const env = EnvSchema.parse(process.env);

// 现在使用类型化的环境变量
console.log(env.PORT); // number

const CreateUserRequest = z.object({
  username: z.string().min(3).max(20),
  email: z.string().email(),
  password: z.string().min(8),
  age: z.number().int().positive().optional(),
});

// Express 示例
app.post("/users", async (req, res) => {
  const result = CreateUserRequest.safeParse(req.body);

  if (!result.success) {
    return res.status(400).json({
      errors: z.flattenError(result.error).fieldErrors,
    });
  }

  const user = await createUser(result.data);
  res.json(user);
});

const FormSchema = z.object({
  firstName: z.string().min(1, "First name required"),
  lastName: z.string().min(1, "Last name required"),
  email: z.string().email("Invalid email"),
  age: z.coerce.number().int().min(18, "Must be 18+"),
  agreeToTerms: z.literal(true, {
    errorMap: () => ({ message: "Must accept terms" }),
  }),
});

type FormData = z.infer<typeof FormSchema>;

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

// 用于 PATCH 请求：使除 id 外的所有字段可选
const UpdateUserSchema = UserSchema.partial().required({ id: true });

type UpdateUser = z.infer<typeof UpdateUserSchema>;
// { id: string; name?: string; email?: string }

// 基础模式
const TimestampSchema = z.object({
  createdAt: z.date(),
  updatedAt: z.date(),
});

const AuthorSchema = z.object({
  authorId: z.string(),
  authorName: z.string(),
});

// 组合成更大的模式
const PostSchema = z.object({
  id: z.string(),
  title: z.string(),
  content: z.string(),
}).merge(TimestampSchema).merge(AuthorSchema);

加载 references/ecosystem-integrations.md 以获取完整的框架和工具集成指南。

ESLint 插件：

eslint-plugin-zod-x - 强制执行最佳实践
eslint-plugin-import-zod - 强制执行导入风格

tRPC - 端到端类型安全 API
React Hook Form - 表单验证（参见 react-hook-form-zod 技能）
Prisma - 从数据库模型生成 Zod
NestJS - DTO 和验证管道

orval - OpenAPI → Zod
Hey API - OpenAPI 转 TypeScript + Zod
kubb - 带有代码生成的 API 工具包

→ 加载 references/ecosystem-integrations.md 以获取： 设置说明、集成示例、Hono 中间件、Drizzle ORM 模式

加载 references/troubleshooting.md 以获取完整的故障排除指南、性能提示和最佳实践。

需要 TypeScript 严格模式 → 在 tsconfig.json 中启用
包体积过大 → 使用 z.lazy() 进行代码分割
异步细化速度慢 → 缓存或防抖
循环依赖 → 使用 z.lazy()
联合类型速度慢 → 使用 z.discriminatedUnion()
转换与细化混淆 → 使用 .refine() 进行验证，.transform() 进行修改

使用 .discriminatedUnion()（比 .union() 快 5-10 倍）
缓存模式实例
使用 .safeParse()（避免 try-catch 开销）
延迟加载大型模式

在模块级别定义模式
使用类型推断（z.infer）
添加自定义错误消息
在系统边界进行验证
组合小型模式
使用 .meta() 进行文档化

→ 加载 references/troubleshooting.md 以获取： 详细解决方案、性能优化、最佳实践、测试模式

// 原始类型
z.string(), z.number(), z.boolean(), z.date(), z.bigint()

// 集合
z.array(), z.tuple(), z.object(), z.record(), z.map(), z.set()

// 特殊类型
z.enum(), z.union(), z.discriminatedUnion(), z.intersection()
z.literal(), z.any(), z.unknown(), z.never()

// 修饰符
.optional(), .nullable(), .nullish(), .default(), .catch()
.readonly(), .brand()

// 验证
.min(), .max(), .length(), .regex(), .email(), .url(), .uuid()
.refine(), .superRefine()

// 转换
.transform(), .pipe(), .codec()

// 解析
.parse(), .safeParse(), .parseAsync(), .safeParseAsync()

// 类型推断
z.infer<typeof Schema>, z.input<typeof Schema>, z.output<typeof Schema>

// 错误处理
z.flattenError(), z.treeifyError(), z.prettifyError()

// JSON Schema
z.toJSONSchema(schema, options)

// 元数据
.meta(), .describe()

// 对象方法
.extend(), .pick(), .omit(), .partial(), .required(), .merge()

何时加载参考文档

加载 references/migration-guide.md 当：

从 Zod v3 升级到 v4 时
有关破坏性变更的问题时
需要迁移清单或回滚策略时
与已弃用 API（.merge(), error.format() 等）相关的错误时
涉及 Infinity 或不安全整数的数字验证问题时

加载 references/error-handling.md 当：

需要为表单或 UI 格式化错误时
实现自定义错误消息时
有关 z.flattenError(), z.treeifyError() 或 z.prettifyError() 的问题时
为错误消息设置本地化时
需要错误代码参考或模式示例时

加载 references/advanced-patterns.md 当：

实现自定义细化或异步验证时
需要双向转换（编解码器）时
处理递归类型或自引用数据时
有关 .refine(), .transform() 或 .codec() 的问题时
需要性能优化模式时
实现条件验证时

加载 references/type-inference.md 当：

有关 TypeScript 类型推断的问题时
需要为 OpenAPI 或 AI 生成 JSON Schema 时
为表单或文档实现元数据系统时
需要类型安全元数据的自定义注册表时
有关 z.infer, z.input, z.output 的问题时
使用品牌类型确保 ID 安全时

加载 references/ecosystem-integrations.md 当：

与 tRPC, React Hook Form, Prisma 或 NestJS 集成时
为最佳实践设置 ESLint 插件时
从 OpenAPI 生成 Zod 模式（orval, Hey API, kubb）时
有关 Hono 中间件或 Drizzle ORM 的问题时
需要框架特定的集成示例时

加载 references/troubleshooting.md 当：

遇到 TypeScript 严格模式错误时
担心包体积或需要延迟加载时
大型联合类型或异步细化的性能问题时
有关循环依赖的问题时
需要最佳实践或测试模式时
混淆 .refine() 和 .transform() 时

官方文档：https://zod.dev
GitHub：https://github.com/colinhacks/zod
TypeScript Playground：https://zod-playground.vercel.app
ESLint 插件（最佳实践）：https://github.com/JoshuaKGoldberg/eslint-plugin-zod-x
tRPC 集成：https://trpc.io
生态系统：https://zod.dev/ecosystem

包版本：4.1.12+（Zod 4.x 稳定版）
零依赖
包体积：2kb（gzip 压缩）
需要 TypeScript 5.5+
需要严格模式
最后验证时间：2025-11-17
技能版本：2.0.0（已更新 v4.1 增强功能）

此版本新增内容：

✨ 包含破坏性变更的全面 v3 到 v4 迁移指南
✨ 具有三级系统的增强错误自定义功能
✨ 带有注册表系统的扩展元数据 API
✨ 带有实际示例的改进错误格式化
✨ 内置对 40+ 种语言的本地化支持
✨ 包含真实世界模式的详细编解码器文档
✨ 解释的性能改进和架构变更

🇺🇸English

Zod: TypeScript-First Schema Validation

Overview

Zod is a TypeScript-first validation library that enables developers to define schemas for validating data at runtime while automatically inferring static TypeScript types. With zero dependencies and a 2kb core bundle (gzipped), Zod provides immutable, composable validation with comprehensive error handling.

Installation

bun add zod
# or
bun add zod
# or
bun add zod
# or
yarn add zod

Requirements :

TypeScript v5.5+ with "strict": true in tsconfig.json
Zod 4.x (4.1.12+)

Important : This skill documents Zod 4.x features. The following APIs require Zod 4 and are NOT available in Zod 3.x:

z.codec() - Bidirectional transformations
z.iso.date(), z.iso.time(), z.iso.datetime(), z.iso.duration() - ISO format validators
z.toJSONSchema() - JSON Schema generation
z.treeifyError(), z.prettifyError(), z.flattenError() - New error formatting helpers
.meta() - Enhanced metadata (Zod 3.x only has .describe())
Unified error parameter - Replaces message, invalid_type_error, required_error, errorMap

For Zod 3.x compatibility or migration guidance, see https://zod.dev

Migrating from Zod v3 to v4

Loadreferences/migration-guide.md for complete v3 to v4 migration documentation.

Quick Summary

Zod v4 introduces breaking changes for better performance:

Error customization : Use unified error parameter (replaces message, invalid_type_error, required_error)
Number validation : Stricter - rejects Infinity and unsafe integers
String formats : Now top-level functions (z.email() vs z.string().email())
Object defaults : Applied even in optional fields
Deprecated APIs : Use .extend() (not .merge()), (not )

→ Loadreferences/migration-guide.md for: Complete breaking changes, migration checklist, gradual migration strategy, rollback instructions

Core Concepts

Basic Usage Pattern

import { z } from "zod";

// Define schema
const UserSchema = z.object({
  username: z.string(),
  age: z.number().int().positive(),
  email: z.string().email(),
});

// Infer TypeScript type
type User = z.infer<typeof UserSchema>;

// Validate data (throws on error)
const user = UserSchema.parse(data);

// Validate data (returns result object)
const result = UserSchema.safeParse(data);
if (result.success) {
  console.log(result.data); // Typed!
} else {
  console.error(result.error); // ZodError
}

Parsing Methods

Use the appropriate parsing method based on error handling needs:

.parse(data) - Throws ZodError on invalid input; returns strongly-typed data on success
.safeParse(data) - Returns { success: true, data } or { success: false, error } (no exceptions)
.parseAsync(data) - For schemas with async refinements/transforms
.safeParseAsync(data) - Async version that doesn't throw

Best Practice : Use .safeParse() to avoid try-catch blocks and leverage discriminated unions.

Primitive Types

Strings

z.string()                    // Basic string
z.string().min(5)            // Minimum length
z.string().max(100)          // Maximum length
z.string().length(10)        // Exact length
z.string().email()           // Email validation
z.string().url()             // URL validation
z.string().uuid()            // UUID format
z.string().regex(/^\d+$/)    // Custom pattern
z.string().startsWith("pre") // Prefix check
z.string().endsWith("suf")   // Suffix check
z.string().trim()            // Auto-trim whitespace
z.string().toLowerCase()     // Auto-lowercase
z.string().toUpperCase()     // Auto-uppercase

// ISO formats (Zod 4+)
z.iso.date()                 // YYYY-MM-DD
z.iso.time()                 // HH:MM:SS
z.iso.datetime()             // ISO 8601 datetime
z.iso.duration()             // ISO 8601 duration

// Network formats
z.ipv4()                     // IPv4 address
z.ipv6()                     // IPv6 address
z.cidrv4()                   // IPv4 CIDR notation
z.cidrv6()                   // IPv6 CIDR notation

// Other formats
z.jwt()                      // JWT token
z.nanoid()                   // Nanoid
z.cuid()                     // CUID
z.cuid2()                    // CUID2
z.ulid()                     // ULID
z.base64()                   // Base64 encoded
z.hex()                      // Hexadecimal

Numbers

z.number()                   // Basic number
z.number().int()             // Integer only
z.number().positive()        // > 0
z.number().nonnegative()     // >= 0
z.number().negative()        // < 0
z.number().nonpositive()     // <= 0
z.number().min(0)            // Minimum value
z.number().max(100)          // Maximum value
z.number().gt(0)             // Greater than
z.number().gte(0)            // Greater than or equal
z.number().lt(100)           // Less than
z.number().lte(100)          // Less than or equal
z.number().multipleOf(5)     // Must be multiple of 5
z.int()                      // Shorthand for z.number().int()
z.int32()                    // 32-bit integer
z.nan()                      // NaN value

Coercion (Type Conversion)

z.coerce.string()            // Convert to string
z.coerce.number()            // Convert to number
z.coerce.boolean()           // Convert to boolean
z.coerce.bigint()            // Convert to bigint
z.coerce.date()              // Convert to Date

// Example: Parse query parameters
const QuerySchema = z.object({
  page: z.coerce.number().int().positive(),
  limit: z.coerce.number().int().max(100).default(10),
});

// "?page=5&limit=20" -> { page: 5, limit: 20 }

Other Primitives

z.boolean()                  // Boolean
z.date()                     // Date object
z.date().min(new Date("2020-01-01"))
z.date().max(new Date("2030-12-31"))
z.bigint()                   // BigInt
z.symbol()                   // Symbol
z.null()                     // Null
z.undefined()                // Undefined
z.void()                     // Void (undefined)

Complex Types

Objects

const PersonSchema = z.object({
  name: z.string(),
  age: z.number(),
  address: z.object({
    street: z.string(),
    city: z.string(),
    country: z.string(),
  }),
});

type Person = z.infer<typeof PersonSchema>;

// Object methods
PersonSchema.shape                 // Access shape
PersonSchema.keyof()              // Get union of keys
PersonSchema.extend({ role: z.string() })  // Add fields
PersonSchema.pick({ name: true }) // Pick specific fields
PersonSchema.omit({ age: true })  // Omit fields
PersonSchema.partial()            // Make all fields optional
PersonSchema.required()           // Make all fields required
PersonSchema.deepPartial()        // Recursively optional

// Strict vs loose objects
z.strictObject({ ... })           // No extra keys allowed (throws)
z.object({ ... })                 // Strips extra keys (default)
z.looseObject({ ... })            // Allows extra keys

Arrays

z.array(z.string())              // String array
z.array(z.number()).min(1)       // At least 1 element
z.array(z.number()).max(10)      // At most 10 elements
z.array(z.number()).length(5)    // Exactly 5 elements
z.array(z.number()).nonempty()   // At least 1 element

// Nested arrays
z.array(z.array(z.number()))     // number[][]

Tuples

z.tuple([z.string(), z.number()]) // [string, number]
z.tuple([z.string(), z.number()]).rest(z.boolean()) // [string, number, ...boolean[]]

Enums and Literals

// Enum
const RoleEnum = z.enum(["admin", "user", "guest"]);
type Role = z.infer<typeof RoleEnum>; // "admin" | "user" | "guest"

// Literal values
z.literal("exact_value")
z.literal(42)
z.literal(true)

// Native TypeScript enum
enum Fruits {
  Apple,
  Banana,
}
z.nativeEnum(Fruits)

// Enum methods
RoleEnum.enum.admin              // "admin"
RoleEnum.exclude(["guest"])      // Exclude values
RoleEnum.extract(["admin", "user"]) // Include only

Unions

// Basic union
z.union([z.string(), z.number()])

// Discriminated union (better performance & type inference)
const ResponseSchema = z.discriminatedUnion("status", [
  z.object({ status: z.literal("success"), data: z.any() }),
  z.object({ status: z.literal("error"), message: z.string() }),
]);

type Response = z.infer<typeof ResponseSchema>;
// { status: "success", data: any } | { status: "error", message: string }

Intersections

const BaseSchema = z.object({ id: z.string() });
const ExtendedSchema = z.object({ name: z.string() });

const Combined = z.intersection(BaseSchema, ExtendedSchema);
// Equivalent to: z.object({ id: z.string(), name: z.string() })

Records and Maps

// Record: object with typed keys and values
z.record(z.string())             // { [key: string]: string }
z.record(z.string(), z.number()) // { [key: string]: number }

// Partial record (some keys optional)
z.partialRecord(z.enum(["a", "b"]), z.string())

// Map
z.map(z.string(), z.number())    // Map<string, number>
z.set(z.string())                // Set<string>

Advanced Patterns

Loadreferences/advanced-patterns.md for complete advanced validation and transformation patterns.

Quick Reference

Refinements (custom validation):

z.string().refine((val) => val.length >= 8, "Too short");
z.object({ password, confirmPassword }).superRefine((data, ctx) => { /* ... */ });

Transformations (modify data):

z.string().transform((val) => val.trim());
z.string().pipe(z.coerce.number());

Codecs (bidirectional transforms - NEW in v4.1):

const DateCodec = z.codec(
  z.iso.datetime(),
  z.date(),
  {
    decode: (str) => new Date(str),
    encode: (date) => date.toISOString(),
  }
);

Recursive Types :

const CategorySchema: z.ZodType<Category> = z.lazy(() =>
  z.object({ name: z.string(), subcategories: z.array(CategorySchema) })
);

Optional/Nullable :

z.string().optional()            // string | undefined
z.string().nullable()            // string | null
z.string().default("default")    // Provides default if undefined

Readonly & Brand:

z.object({ ... }).readonly()     // Readonly properties
z.string().brand<"UserId">()     // Nominal typing

→ Loadreferences/advanced-patterns.md for: Complete refinement patterns, async validation, codec examples, composable schemas, conditional validation, performance optimization

Error Handling

Loadreferences/error-handling.md for complete error formatting and customization guide.

Quick Reference

Error Formatting Methods :

// For forms
const { fieldErrors } = z.flattenError(error);

// For nested data
const tree = z.treeifyError(error);
const nameError = tree.properties?.user?.properties?.name?.errors?.[0];

// For debugging
console.log(z.prettifyError(error));

Custom Error Messages (three levels):

// 1. Schema-level (highest priority)
z.string({ error: "Custom message" });
z.string().min(5, "Too short");

// 2. Per-parse level
schema.parse(data, { error: (issue) => ({ message: "..." }) });

// 3. Global level
z.config({ customError: (issue) => ({ message: "..." }) });

Localization (40+ languages):

z.config(z.locales.es());  // Spanish
z.config(z.locales.fr());  // French

→ Loadreferences/error-handling.md for: Complete error formatting examples, custom error patterns, localization setup, error code reference

Type Inference

Loadreferences/type-inference.md for complete type inference and metadata documentation.

Quick Reference

Basic Type Inference :

const UserSchema = z.object({ name: z.string() });
type User = z.infer<typeof UserSchema>; // { name: string }

Input vs Output (for transforms):

const TransformSchema = z.string().transform((s) => s.length);
type Input = z.input<typeof TransformSchema>;   // string
type Output = z.output<typeof TransformSchema>; // number

JSON Schema Conversion :

const jsonSchema = z.toJSONSchema(UserSchema, {
  target: "openapi-3.0",
  metadata: true,
});

Metadata :

// Add metadata
const EmailSchema = z.string().email().meta({
  title: "Email Address",
  description: "User's email address",
});

// Create custom registry
const formRegistry = z.registry<FormFieldMeta>();

→ Loadreferences/type-inference.md for: Complete type inference patterns, JSON Schema options, metadata system, custom registries, brand types

Functions

Validate function inputs and outputs:

const AddFunction = z.function()
  .args(z.number(), z.number())  // Arguments
  .returns(z.number());           // Return type

// Implement typed function
const add = AddFunction.implement((a, b) => {
  return a + b; // Type-checked!
});

// Async functions
const FetchFunction = z.function()
  .args(z.string())
  .returns(z.promise(z.object({ data: z.any() })))
  .implementAsync(async (url) => {
    const response = await fetch(url);
    return response.json();
  });

Common Patterns

Environment Variables

const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "production", "test"]),
  DATABASE_URL: z.string().url(),
  PORT: z.coerce.number().int().positive().default(3000),
  API_KEY: z.string().min(32),
});

// Validate on startup
const env = EnvSchema.parse(process.env);

// Now use typed env
console.log(env.PORT); // number

API Request Validation

const CreateUserRequest = z.object({
  username: z.string().min(3).max(20),
  email: z.string().email(),
  password: z.string().min(8),
  age: z.number().int().positive().optional(),
});

// Express example
app.post("/users", async (req, res) => {
  const result = CreateUserRequest.safeParse(req.body);

  if (!result.success) {
    return res.status(400).json({
      errors: z.flattenError(result.error).fieldErrors,
    });
  }

  const user = await createUser(result.data);
  res.json(user);
});

Form Validation

const FormSchema = z.object({
  firstName: z.string().min(1, "First name required"),
  lastName: z.string().min(1, "Last name required"),
  email: z.string().email("Invalid email"),
  age: z.coerce.number().int().min(18, "Must be 18+"),
  agreeToTerms: z.literal(true, {
    errorMap: () => ({ message: "Must accept terms" }),
  }),
});

type FormData = z.infer<typeof FormSchema>;

Partial Updates

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

// For PATCH requests: make everything optional except id
const UpdateUserSchema = UserSchema.partial().required({ id: true });

type UpdateUser = z.infer<typeof UpdateUserSchema>;
// { id: string; name?: string; email?: string }

Composable Schemas

// Base schemas
const TimestampSchema = z.object({
  createdAt: z.date(),
  updatedAt: z.date(),
});

const AuthorSchema = z.object({
  authorId: z.string(),
  authorName: z.string(),
});

// Compose into larger schemas
const PostSchema = z.object({
  id: z.string(),
  title: z.string(),
  content: z.string(),
}).merge(TimestampSchema).merge(AuthorSchema);

Ecosystem Integration

Loadreferences/ecosystem-integrations.md for complete framework and tooling integration guide.

Quick Reference

ESLint Plugins :

eslint-plugin-zod-x - Enforces best practices
eslint-plugin-import-zod - Enforces import style

Framework Integrations :

tRPC - End-to-end typesafe APIs
React Hook Form - Form validation (see react-hook-form-zod skill)
Prisma - Generate Zod from database models
NestJS - DTOs and validation pipes

Code Generation :

orval - OpenAPI → Zod
Hey API - OpenAPI to TypeScript + Zod
kubb - API toolkit with codegen

→ Loadreferences/ecosystem-integrations.md for: Setup instructions, integration examples, Hono middleware, Drizzle ORM patterns

Troubleshooting

Loadreferences/troubleshooting.md for complete troubleshooting guide, performance tips, and best practices.

Quick Reference

Common Issues :

TypeScript strict mode required → Enable in tsconfig.json
Large bundle size → Use z.lazy() for code splitting
Slow async refinements → Cache or debounce
Circular dependencies → Use z.lazy()
Slow unions → Use z.discriminatedUnion()
Transform vs refine confusion → Use .refine() for validation, .transform() for modification

Performance Tips :

Use .discriminatedUnion() (5-10x faster than .union())
Cache schema instances
Use .safeParse() (avoids try-catch overhead)
Lazy load large schemas

Best Practices :

Define schemas at module level
Use type inference (z.infer)
Add custom error messages
Validate at system boundaries
Compose small schemas
Document with .meta()

→ Loadreferences/troubleshooting.md for: Detailed solutions, performance optimization, best practices, testing patterns

Quick Reference

// Primitives
z.string(), z.number(), z.boolean(), z.date(), z.bigint()

// Collections
z.array(), z.tuple(), z.object(), z.record(), z.map(), z.set()

// Special types
z.enum(), z.union(), z.discriminatedUnion(), z.intersection()
z.literal(), z.any(), z.unknown(), z.never()

// Modifiers
.optional(), .nullable(), .nullish(), .default(), .catch()
.readonly(), .brand()

// Validation
.min(), .max(), .length(), .regex(), .email(), .url(), .uuid()
.refine(), .superRefine()

// Transformation
.transform(), .pipe(), .codec()

// Parsing
.parse(), .safeParse(), .parseAsync(), .safeParseAsync()

// Type inference
z.infer<typeof Schema>, z.input<typeof Schema>, z.output<typeof Schema>

// Error handling
z.flattenError(), z.treeifyError(), z.prettifyError()

// JSON Schema
z.toJSONSchema(schema, options)

// Metadata
.meta(), .describe()

// Object methods
.extend(), .pick(), .omit(), .partial(), .required(), .merge()

When to Load References

Loadreferences/migration-guide.md when:

Upgrading from Zod v3 to v4
Questions about breaking changes
Need migration checklist or rollback strategy
Errors related to deprecated APIs (.merge(), error.format(), etc.)
Number validation issues with Infinity or unsafe integers

Loadreferences/error-handling.md when:

Need to format errors for forms or UI
Implementing custom error messages
Questions about z.flattenError(), z.treeifyError(), or z.prettifyError()
Setting up localization for error messages
Need error code reference or pattern examples

Loadreferences/advanced-patterns.md when:

Implementing custom refinements or async validation
Need bidirectional transformations (codecs)
Working with recursive types or self-referential data
Questions about .refine(), .transform(), or .codec()
Need performance optimization patterns
Implementing conditional validation

Loadreferences/type-inference.md when:

Questions about TypeScript type inference
Need to generate JSON Schema for OpenAPI or AI
Implementing metadata system for forms or documentation
Need custom registries for type-safe metadata
Questions about z.infer, z.input, z.output
Using brand types for ID safety

Loadreferences/ecosystem-integrations.md when:

Integrating with tRPC, React Hook Form, Prisma, or NestJS
Setting up ESLint plugins for best practices
Generating Zod schemas from OpenAPI (orval, Hey API, kubb)
Questions about Hono middleware or Drizzle ORM
Need framework-specific integration examples

Loadreferences/troubleshooting.md when:

Encountering TypeScript strict mode errors
Bundle size concerns or lazy loading needs
Performance issues with large unions or async refinements
Questions about circular dependencies
Need best practices or testing patterns
Confusion between .refine() and .transform()

Additional Resources

Official Docs : https://zod.dev
GitHub : https://github.com/colinhacks/zod
TypeScript Playground : https://zod-playground.vercel.app
ESLint Plugin (Best Practices) : https://github.com/JoshuaKGoldberg/eslint-plugin-zod-x
tRPC Integration : https://trpc.io
Ecosystem : https://zod.dev/ecosystem

Production Notes :

Package version: 4.1.12+ (Zod 4.x stable)
Zero dependencies
Bundle size: 2kb (gzipped)
TypeScript 5.5+ required
Strict mode required
Last verified: 2025-11-17
Skill version: 2.0.0 (Updated with v4.1 enhancements)

What's New in This Version :

✨ Comprehensive v3 to v4 migration guide with breaking changes
✨ Enhanced error customization with three-level system
✨ Expanded metadata API with registry system
✨ Improved error formatting with practical examples
✨ Built-in localization support for 40+ locales
✨ Detailed codec documentation with real-world patterns
✨ Performance improvements and architectural changes explained

Weekly Installs

157

Repository

secondsky/claude-skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode127

gemini-cli119

github-copilot117

codex117

claude-code114

cursor111

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

116,600 周安装

Function validation : Use .implement() method

UUID validation : Stricter RFC 9562/4122 compliance

Zod TypeScript 模式验证库：运行时数据验证与静态类型推断

🇨🇳中文介绍

Zod：TypeScript 优先的模式验证

概述

安装

相关 Skills

从 Zod v3 迁移到 v4

快速摘要

核心概念

基本使用模式

解析方法

原始类型

字符串

数字

强制转换（类型转换）

其他原始类型

复杂类型

对象

数组

元组

枚举和字面量

联合类型

交集类型

记录和映射

高级模式

快速参考

错误处理

快速参考

类型推断

快速参考

函数

常见模式

环境变量

API 请求验证

表单验证

部分更新

可组合模式

生态系统集成

快速参考

故障排除

快速参考

快速参考

何时加载参考文档

其他资源

🇺🇸English

Zod: TypeScript-First Schema Validation

Overview

Installation

Migrating from Zod v3 to v4

Quick Summary

Core Concepts

Basic Usage Pattern

Parsing Methods

Primitive Types

Strings

Numbers

Coercion (Type Conversion)

Other Primitives

Complex Types

Objects

Arrays

Tuples

Enums and Literals

Unions

Intersections

Records and Maps

Advanced Patterns

Quick Reference

Error Handling

Quick Reference

Type Inference

Quick Reference

Functions

Common Patterns

Environment Variables

API Request Validation

Form Validation

Partial Updates

Composable Schemas

Ecosystem Integration