在 TypeScript 生态中，Zod 是最具代表性的 schema 校验库之一，作者是 Colin McDonnell（@colinhacks）。Zod 4 已经稳定，最新版本 4.5 已发布，官方同时提供了发布说明与迁移指南。它的核心卖点可以概括为：核心包仅 2kb（gzipped）、零外部依赖、校验结果自带静态类型推断。

Zod 是什么

Zod 的用法是先定义数据的形状（schema），再对运行时数据做解析。schema 定义一次，校验逻辑与 TypeScript 类型就从同一份定义中派生出来。

import * as z from "zod";

const User = z.object({
  name: z.string(),
});

// input 来自外部，类型未知
const input = { name: "Alice" };

// 校验通过，data 的类型自动推断为 { name: string }
const data = User.parse(input);

先定义 schema、再解析数据，让「校验」与「类型」来自同一份定义，从源头消除运行时数据与类型声明不一致的问题。

核心特性

Zod 官方列出的特性清单包括：

  • 核心包仅 2kb（gzipped）：体积小，前端与 Node.js 场景都适用。
  • 零外部依赖：安装干净，不拖入其他依赖。
  • 不可变 API：方法都返回新实例，不修改原有 schema。
  • 内置 JSON Schema 转换：schema 可直接转换为 JSON Schema，方便与其他工具链对接。
  • TypeScript 与纯 JavaScript 均可用：不强制使用 TS。
  • 支持 Node.js 与所有现代浏览器。

版本要求

Zod 官方测试基线是 TypeScript v5.5 及以上，更旧的版本可能能用但不保证支持。官方同时建议项目开启 strict 模式——这也是 TypeScript 项目通用的最佳实践。

// tsconfig.json
{
  "compilerOptions": {
    "strict": true
  }
}

生态联动

Zod 的生态覆盖了多个知名项目与工具：

  • tRPC：端到端类型安全的 API 方案，直接使用 Zod schema。
  • React Hook Form：官方提供 Zod resolver，表单校验与 Zod 无缝衔接。
  • zshy：作者维护的 TypeScript 库构建工具，最初就是 Zod 的内部构建工具。

安装方式有两种：npm 上执行 npm install zod，或使用 jsr.io 上的 @zod/zod。项目还提供 MCP server，AI 智能体可以直接检索 Zod 官方文档，并提供了 llms.txt 文件供大模型工具读取。

适用场景

如果 TypeScript 项目需要校验来自 API、表单或配置文件的数据，Zod 的投入产出比很高：2kb 的体积、零依赖、类型自动推断，既能充当运行时防线，也不会给项目增加负担。对使用 tRPC 或 React Hook Form 的项目，Zod 几乎是现成的配套选择。