用途:Zod 是 TypeScript 优先的 Schema 声明与校验库,用 z.infer<> 从同一份 Schema 同时得到运行时校验与 TypeScript 类型,避免运行时检查与类型定义脱节。官方推荐版本为 Zod 4(2025),Zod 3.x 亦被广泛使用;要求 TypeScript ≥5.5 并开启 strict 模式。
主要能力:支持字符串、数字、枚举等基础类型及其校验(email、url、uuid、min、max 等);用对象 Schema 描述结构,并通过 omit、partial、pick 派生创建、更新、公开响应等变体;支持 discriminatedUnion 实现类型安全的 API 响应;可用 refine 做自定义校验、superRefine 做跨字段校验;支持 transform 做数据归一化、z.coerce 做查询参数类型转换;内置分页、日期区间、环境变量、文件上传元数据等常用配方。
使用方式:安装 npm install zod。定义 Schema 后,用 .parse(data) 会抛异常,.safeParse(data) 返回 { success, data?, error? };异步版本为 .parseAsync 与 .safeParseAsync。应用代码建议用 .safeParse(),可信上下文用 .parse()。可与 tRPC 集成(作为 .input() 自动校验)、与 react-hook-form 配合构建表单,也可用于解析 process.env。建议将 Schema 放在 /schemas/*.schema.ts 等专用文件中。
适用场景:API 输入校验、表单校验、环境变量与配置文件或 JSON 解析、各层之间的 DTO、任何跨越信任边界的数据。
限制:不适合复杂业务规则校验(应使用领域逻辑)、数据库 Schema 定义(应使用 Prisma schema)或纯静态类型定义(应使用 interface)。tRPC 输入不支持异步 transform;输出 Schema 搭配 .catchall() 存在类型推断问题;多个 Zod 安装副本会导致类型推断失败;过度复杂的嵌套 refine 难以调试。
官方文档见 https://zod.dev,源码见 https://github.com/colinhacks/zod。