用途:Zod 用于 TypeScript 项目中的数据 schema 定义与校验,可处理表单、接口响应、配置等输入,并自动推断静态类型。官方资料提示训练数据中的 Zod 信息可能不可靠,写代码前应先用 WebFetch 读取实时文档(如 https://zod.dev/llms.txt)。
主要能力:内置常见格式校验(email、URL、UUID、CUID、ISO 8601 datetime、IP、MAC、JWT、哈希等),无需外部校验包;z.coerce.* 自动转换输入(如表单字符串转数字);.transform() 一步转换解析值;z.treeifyError()、z.prettifyError()、z.flattenError() 格式化错误;z.pipe() 与 codec 模式支持双向编解码(encode + decode),如 stringToNumber、base64ToBytes。资料称这些最佳实践面向 Zod v4(通过 npm install zod 安装),顶层错误工具为 v4 独有,v3 中为实例方法。
用法要点:应用代码优先用 .safeParse() 而非 .parse(),前者返回 { success, data, error },可避免 try/catch,.parse() 仅用于故意抛出未处理异常的场景(如启动配置校验)。类型应从 schema 推断,使用 z.infer<typeof MySchema>,保持 schema 为唯一来源。.transform() 会改变输出类型;refine 在 transform 之后运行,收到的是转换后的值;跨字段校验用 .superRefine() 而非多个链式 .refine()。注意 z.coerce 会把 null 转为 0、undefined 转为 NaN,若空值应表示缺失,应改用 z.preprocess()。
限制:资料未提供价格、平台与性能数据;版本升级需参考迁移指南。