v4 重写带来的变化

v4 性能对比

场景	v3	v4	提升
parse 简单对象	1x	~14x	解析核心重写
bundle 大小	~45KB	~12KB	3x 缩减
@zod/mini	N/A	~2KB	函数式超精简
TS 编译速度	1x	~2x	类型简化

Colin 在博客里给了测试数据:10 万次 parse 一个 10 字段 object,v3 约 2.1s,v4 约 0.14s。bundle 变小主要靠去掉了冗余的 runtime 辅助。

v4 新 API:z.iso

z.iso.date();        // "2026-05-06"
z.iso.datetime();    // "2026-05-06T10:00:00Z"
z.iso.time();        // "10:00:00"
z.iso.duration();    // "P1Y2M3DT4H5M6S"

v3 的 z.string().datetime() 还在但不推荐。z.iso 命名空间更语义化,还支持 { offset: true } 等参数。

v4 新 API:错误接口变化

// v3
schema.parse(data); // ZodError 里 issue.message 是字符串

// v4:可以用 top-level z.prettifyError
console.log(z.prettifyError(err));

// v4:treeify 变 format
err.format();        // 还在
err.flatten();       // 还在

// v4 issues 包含新 code(更规整的 code 枚举)

v4 新 API:record 签名

// v3 允许
z.record(z.number());
// v4 要求同时传 key 和 value
z.record(z.string(), z.number());

v4 把 key 也变成可校验——可以限制 key 只能是某些 literal / enum,防止"万能 bag"误用。

从 v3 迁到 v4

@zod/mini:超精简版

pnpm add @zod/mini

import * as z from "@zod/mini";

const User = z.object({
  email: z.email(),            // 顶层函数,不是链式
  age: z.pipe(z.number(), z.int(), z.min(0)),
});

// bundle 约 2KB(tree-shake 后)
// 适合:边缘函数(Cloudflare Workers / Deno)、对 bundle 极敏感的浏览器端

@zod/mini 是 Valibot 式函数 API 的 Zod 版——用 pipe() 组合,tree-shake 极致。代价是写法不如链式流畅。

	zod	@zod/mini
API 风格	链式 .min(1)	函数 pipe(..., min(1))
Bundle	~12KB	~2KB
Tree-shaking	好	极好
人体工学	优秀	够用
互兼容	两边 schema 可互操作,z.infer 类型也一致

Standard Schema

2024 起 Zod / Valibot / ArkType 三大库达成共识——Standard Schema 规范定义了共同接口(~standard 字段),下游库(TanStack Form、drizzle-zod、UnpluginIcons 等)只需对接一次,三库通吃。

import type { StandardSchemaV1 } from "@standard-schema/spec";

async function validate<T>(schema: StandardSchemaV1<T>, input: unknown) {
  let result = schema["~standard"].validate(input);
  if (result instanceof Promise) result = await result;
  if (result.issues) throw new Error(JSON.stringify(result.issues));
  return result.value;
}

// 这个函数能吃 Zod / Valibot / ArkType schema —— 用户可选

Zod v4 内置 Standard Schema——你的 API 如果对接 StandardSchemaV1,用户可以选择任何合规库,对后端来说无感。

Zod vs Valibot

	Zod v4	Valibot
API	链式 OO 风格	函数式 pipe
Bundle(Valibot 风格)	@zod/mini ~2KB	~2KB
生态	碾压性大	小但成长
TS 推断	优秀	优秀
文档	非常完备	好
维护	Colin 全职	社区活跃

Valibot 在边缘函数 / 原生 bundle 敏感的场景还有一点优势,但 @zod/mini 的出现基本拉平了差距。生态上 Zod 仍占压倒性优势。

Zod vs ArkType

import { type } from "arktype";

const User = type({
  name: "string > 2",
  age: "number.integer >= 0",
  email: "string.email",
});

// ArkType 特色:用字符串 DSL 定义 schema,TS 做字符串解析

ArkType 把约束写成字符串,由 TypeScript 在类型层解析——运行时极快、类型超精准,但学习曲线高一些,生态也小。适合"愿意学新 DSL 换极致性能"的场景。Zod 仍是默认选择。

Zod + Vercel AI SDK

import { streamObject } from "ai";
import { openai } from "@ai-sdk/openai";

const Report = z.object({
  title: z.string(),
  sections: z.array(z.object({
    heading: z.string(),
    content: z.string(),
  })),
});

const { partialObjectStream } = await streamObject({
  model: openai("gpt-4o"),
  schema: Report,
  prompt: "生成一份关于 AI 的报告",
});

for await (const partial of partialObjectStream) {
  updateUI(partial);   // partial 类型是 DeepPartial<Report>
}

Zod + tRPC v11

// tRPC v11 支持任何 Standard Schema,但 Zod 仍是一等公民
publicProcedure
  .input(ZodSchema)
  .mutation(...);

// 也可以换成 Valibot schema —— 用户无感

Zod + Drizzle / Prisma

// Drizzle
import { createSelectSchema, createInsertSchema } from "drizzle-zod";

// Prisma
import { UserSchema } from "./generated/zod";    // prisma-zod-generator

// 两者都把 DB 模型 → Zod schema 自动化

框架 / 库支持一览

生产建议

未来方向(2026+)

• 更快的 TS 编译——Colin 正在解决大 schema 编译慢的问题
• 更精细的 tree-shaking——让 @zod/mini 也能写链式
• JSON Schema 互转——zod-to-json-schema / json-schema-to-zod 双向同步
• 更好的 coerce 规则——解决 boolean("false") === true 这类陷阱
• 原生 Async Iterator schema——支持流式验证

本章小结