Zod 是 TypeScript 优先的模式校验库,核心用途是用一份模式定义同时获得运行时校验与静态类型推断。安装命令:npm install zod。
主要能力:支持字符串、数字、布尔、日期、BigInt、null/undefined 等基础类型及其约束(如 min/max/email/url/uuid/regex);对象模式支持 partial、required、pick、omit、extend、merge,以及 strict、passthrough、strip 控制未知键;数组与元组支持长度与类型限制;联合、可辨识联合、枚举、原生枚举与字面量类型。
转换与解析:transform 可在校验后转换值,pipe 可串联校验,coerce 支持自动类型强制转换,preprocess 可在校验前处理数据,default 与 catch 提供默认值。refine 与 superRefine 支持自定义校验及多问题上报,refine 也可实现跨字段校验(如密码确认)。
错误处理:safeParse 返回成功标志与数据或 ZodError,parse 在失败时抛错;可通过 flatten、format 或遍历 issues 获取错误信息,并可为字段设置自定义错误文案。
类型推断:使用 z.infer 获取输出类型,z.input 与 z.output 区分转换前后类型。常见用法包括 API 请求校验、环境变量校验、表单数据解析,以及配合 react-hook-form 的 zodResolver 和 Next.js Server Actions 使用。
限制与注意事项:应优先使用 safeParse 而非无 try/catch 的 parse;避免重复定义类型,改用 z.infer;注意转换前后输入输出类型不同;模式过于复杂时应拆分。资料中未提供收费、价格与平台支持等具体信息。