zod

Zod 是一个 TypeScript 优先的验证库。您可以定义一个模式，用它解析数据，并接收一个强类型、已验证的结果。它适用于 Node.js 和现代浏览器，没有外部依赖，并提供一个小型核心包（gzip 压缩后约 2kb）。API 是不可变的：方法返回一个新实例，而不是修改现有模式。它可以在 TypeScript 或纯 JavaScript 中使用，并包含内置的 JSON Schema 转换功能。 基本用法从定义模式开始，例如一个包含字符串和数字字段的对象。在模式上调用 `.parse` 会验证输入并返回一个强类型的深层克隆。如果模式使用异步细化或转换，则需要使用 `.parseAsync()`。当验证失败时，`.parse()` 会抛出一个 `ZodError`，其中包含详细的问题信息，例如预期类型、错误代码、违规字段的路径和消息。为了避免 try/catch，`.safeParse()` 返回一个可辨识联合，其中包含解析的数据或错误；`.safeParseAsync()` 则处理异步模式。 可以使用 `z.infer<>` 从模式中推断类型。当输入和输出类型不同时，例如通过 `.transform()`，`z.input<>` 和 `z.output<>` 可以独立提取它们。 一个显著的特性是预先编译（ahead-of-time compilation）。`z.compile(schema)` 返回一个模式克隆，其中包含针对有效输入的编译快速路径，而无效输入则回退到常规解析器，因此错误报告保持不变。README 报告称，在 55 个模式的基准测试中，中位数加速达到 2.4 倍，并随模式复杂性而变化（大型对象数组和 20 键对象约 9 倍，嵌套对象约 4.5 倍，而裸字符串模式则没有增益）。编译也可以通过在定义模式的模块之前导入 `zod/compile` 来全局启用。编译使用 `new Function`，当设置 `z.config({ jitless: true })` 时（例如在 CSP 环境中），全局模式会自动禁用；直接调用 `z.compile()` 是一种明确的选择加入。包含异步细化或转换以及其他一些构造的模式无法编译；在这种情况下，`z.compile()` 返回未更改的模式，并继续使用常规解析器，除非传入 `{ strict: true }` 以抛出特定错误。对于无效输入，细化和转换可能会运行两次。从已编译模式派生新模式会返回一个未编译的模式，因此最终模式应该被编译。 安装通过 `npm install zod` 进行。该项目链接到 zod.dev 上的文档、一个 Discord 社区和社交渠道。它采用 MIT 许可证。