TypeScript 运行时验证终极对比：Zod vs Valibot vs ArkType 深度评测

TypeScript 的类型系统在编译时为你挡住了大量 Bug，但一旦代码运行起来，所有类型信息都会被擦除——从 API 响应、表单提交到环境变量，外部数据永远不会遵守你定义的接口。根据 State of JS 2025 调查，83% 的 TypeScript 开发者在生产项目中使用了运行时验证库，其中 Zod 以 67% 的使用率稳居第一。但 2026 年的格局正在发生变化：Valibot 凭借 10 倍的体积优势和 3 倍的性能提升快速崛起，ArkType 则用最接近原生 TypeScript 的语法重新定义了 Schema 编写体验。本文将从实际项目角度出发，帮你做出最适合的选择。

🔍 一、三大框架核心对比

1.1 为什么需要运行时验证？

TypeScript 的类型只存在于编译阶段。当你写下 interface User { name: string; age: number }，编译成 JavaScript 后这行代码完全消失。这意味着：

// 运行时从 API 拿到的数据可能完全不符合预期
const response = await fetch('/api/user')
const user = await response.json()
// user 可能是 { name: 123, age: "abc" } 甚至 null
// TypeScript 不会在运行时报错！

运行时验证库的核心价值就是：在数据进入你的程序边界时，立即检查它是否合法。这不是可选的防御措施，而是生产级应用的基本要求。

📌 **记住：**永远不要信任外部数据。无论是 API 响应、用户输入还是环境变量，都必须经过运行时验证。

1.2 三款框架速览

⚡ **关键结论：**Zod 是生态之王，Valibot 是性能之王，ArkType 是 DX（开发体验）之王。没有银弹，选型取决于你的项目需求。

🚀 二、实战代码对比

2.1 Schema 定义方式

三款框架定义同一个 User Schema，写法差异非常明显：

// Zod — 链式 API，最经典
import { z } from 'zod'

const UserSchemaZod = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
  age: z.number().int().min(0).max(150),
  role: z.enum(['admin', 'user', 'guest']),
  tags: z.array(z.string()).default([]),
  address: z.object({
    city: z.string(),
    zipCode: z.string().regex(/^\d{6}$/)
  }).optional()
})

// Valibot — 链式 API，但完全可 tree-shake
import * as v from 'valibot'

const UserSchemaValibot = v.object({
  name: v.pipe(v.string(), v.minLength(1), v.maxLength(100)),
  email: v.pipe(v.string(), v.email()),
  age: v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(150)),
  role: v.picklist(['admin', 'user', 'guest']),
  tags: v.optional(v.array(v.string()), []),
  address: v.optional(v.object({
    city: v.string(),
    zipCode: v.pipe(v.string(), v.regex(/^\d{6}$/))
  }))
})

// ArkType — 最接近原生 TypeScript 语法
import { type } from 'arktype'

const UserSchemaArkType = type({
  name: '1<=string<=100',
  email: 'email',
  age: '0<=integer<=150',
  role: "'admin' | 'user' | 'guest'",
  tags: 'string[] = []',
  address: {
    city: 'string',
    zipCode: '/^\\d{6}$/'
  } + '?'
})

💡 **提示：**ArkType 的语法最简洁，但学习曲线也最陡——你需要记住它的类型表达式语法。Zod 最"传统"但可读性好，Valibot 的 pipe 模式在复杂校验时比 Zod 的链式调用更灵活。

2.2 数据解析与错误处理

// Zod 解析与错误处理
const result = UserSchemaZod.safeParse(invalidData)
if (!result.success) {
  console.log(result.error.issues)
  // [{ code: 'too_small', minimum: 1, path: ['name'], message: '...' }]
}

// Valibot 解析与错误处理
const result2 = v.safeParse(UserSchemaValibot, invalidData)
if (!result2.issues) {
  console.log(result2.output)
} else {
  console.log(result2.issues)
  // [{ kind: 'validation', type: 'min_length', path: [...], message: '...' }]
}

// ArkType 解析与错误处理
const result3 = UserSchemaArkType(invalidData)
if (result3 instanceof type.errors) {
  console.log(result3.summary)
  // "name must be at least 1 character..."
}

在错误信息的丰富度上，Zod 和 Valibot 提供了结构化的错误对象（包含 path、code、message），方便做表单字段级别的错误映射。ArkType 默认只给一个可读的 summary 字符串，虽然简洁但在复杂表单场景中不太方便。

2.3 高级用法：Transform 与 Pipe

在实际项目中，你经常需要在验证的同时转换数据。比如把日期字符串转成 Date 对象，或把字符串数字转成真正的数字：

// Zod — 使用 transform
const OrderSchema = z.object({
  id: z.string().uuid(),
  amount: z.string().transform(Number),
  createdAt: z.string().datetime().transform(s => new Date(s)),
  items: z.array(z.object({
    productId: z.string(),
    quantity: z.coerce.number().int().positive()
  })).min(1)
})

// Valibot — 使用 pipe 串联验证和转换
const OrderSchemaValibot = v.object({
  id: v.pipe(v.string(), v.uuid()),
  amount: v.pipe(v.string(), v.transform(Number)),
  createdAt: v.pipe(v.string(), v.isoDateTime(), v.transform(s => new Date(s))),
  items: v.pipe(
    v.array(v.object({
      productId: v.string(),
      quantity: v.pipe(v.string(), v.transform(Number), v.integer(), v.minValue(1))
    })),
    v.nonEmpty()
  )
})

⚠️ 警告：z.coerce.number() 会静默地把 "abc" 转成 NaN，你需要额外加 .refine(v => !isNaN(v))。Valibot 的 v.transform(Number) 也有同样的问题——永远要在 transform 后加验证。

2.4 Discriminated Union（判别联合类型）

在处理多态 API 响应时，判别联合类型是必不可少的模式。比如支付方式可以是信用卡、PayPal 或银行转账，每种方式的字段完全不同：

// Zod — 使用 z.discriminatedUnion
const PaymentSchema = z.discriminatedUnion('method', [
  z.object({
    method: z.literal('credit_card'),
    cardNumber: z.string().regex(/^\d{16}$/),
    expiry: z.string().regex(/^\d{2}\/\d{2}$/),
    cvv: z.string().regex(/^\d{3,4}$/)
  }),
  z.object({
    method: z.literal('paypal'),
    email: z.string().email()
  }),
  z.object({
    method: z.literal('bank_transfer'),
    bankCode: z.string().min(4),
    accountNumber: z.string().min(8)
  })
])

// Valibot — 使用 v.variant
const PaymentSchemaValibot = v.variant('method', [
  v.object({
    method: v.literal('credit_card'),
    cardNumber: v.pipe(v.string(), v.regex(/^\d{16}$/)),
    expiry: v.pipe(v.string(), v.regex(/^\d{2}\/\d{2}$/)),
    cvv: v.pipe(v.string(), v.regex(/^\d{3,4}$/))
  }),
  v.object({
    method: v.literal('paypal'),
    email: v.pipe(v.string(), v.email())
  }),
  v.object({
    method: v.literal('bank_transfer'),
    bankCode: v.pipe(v.string(), v.minLength(4)),
    accountNumber: v.pipe(v.string(), v.minLength(8))
  })
])

判别联合类型的价值在于：验证器只需要检查 method 字段就能确定用哪个子 Schema，性能远优于逐个尝试所有分支。Zod 的 discriminatedUnion 和 Valibot 的 variant 都是 O(1) 分发，而普通的 z.union 是 O(n) 尝试。

📊 三、性能与体积基准测试

这是很多开发者关心但很少有人实际测量的部分。我在同一台机器上（Node.js v22.4, Apple M2）对三款框架做了基准测试。

3.1 解析性能

测试方法：对一个包含 10 个字段的嵌套对象 Schema，执行 100,000 次 safeParse（有效数据和无效数据各半）。

ArkType 和 Valibot 在解析性能上碾压 Zod。原因在于 Zod 的实现包含了大量的内部包装和元数据收集，在高频场景下（如 API 网关每秒处理数千请求）这个差距会很明显。

3.2 Bundle 体积

⚡ **关键结论：**Valibot 的 tree-shake 设计意味着你只打包实际使用的验证函数。如果你只用了 string()、number() 和 object()，最终 bundle 可能只有几百字节。这对前端应用和 Serverless 函数尤为重要。

3.3 首次 Schema 编译时间

ArkType 有一个独特的特点：它在定义 Schema 时会进行编译，首次调用较慢，后续调用极快。这对「定义一次、使用多次」的场景（如 API Schema）非常理想，但在需要频繁创建临时 Schema 的场景中可能会有冷启动问题。

// ArkType 首次编译耗时：~2ms（简单 Schema）到 ~50ms（复杂嵌套 Schema）
// 后续调用：~0.001ms/次
// Zod 首次定义：~0.01ms，每次解析：~0.003ms
// Valibot 首次定义：~0.005ms，每次解析：~0.001ms

🛠️ 四、生态集成与实战场景

4.1 与主流框架的集成

选择验证库不只看库本身，还要看它和你的技术栈能不能无缝衔接：

如果你的技术栈是 tRPC + Next.js + Drizzle，Zod 几乎是零摩擦的选择。如果你用的是 Hono 或更轻量的框架，Valibot 的体积优势更明显。

4.2 表单验证实战

前端表单验证是最常见的场景。下面展示 Zod + React Hook Form 的完整集成：

// 完整的表单验证示例：Zod + React Hook Form
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { z } from 'zod'

const LoginSchema = z.object({
  email: z.string().email('请输入有效的邮箱地址'),
  password: z.string()
    .min(8, '密码至少 8 位')
    .regex(/[A-Z]/, '密码需包含大写字母')
    .regex(/[0-9]/, '密码需包含数字'),
  rememberMe: z.boolean().default(false)
})

type LoginForm = z.infer<typeof LoginSchema>

function LoginForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<LoginForm>({
    resolver: zodResolver(LoginSchema)
  })

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} />
      {errors.email && <span>{errors.email.message}</span>}

      <input type="password" {...register('password')} />
      {errors.password && <span>{errors.password.message}</span>}

      <button type="submit">登录</button>
    </form>
  )
}

z.infer<typeof LoginSchema> 会自动从 Schema 推断出 TypeScript 类型，这意味着你只需要维护一份 Schema，类型和验证逻辑完全同步——这是运行时验证库最大的价值之一。

4.3 API 路由参数校验

后端 API 路由校验是另一个高频场景。以 Hono 框架为例：

// Hono + Zod 中间件校验
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const app = new Hono()

const CreateUserSchema = z.object({
  name: z.string().min(1).max(50),
  email: z.string().email(),
  age: z.number().int().min(0).max(150),
  department: z.enum(['engineering', 'design', 'product', 'marketing'])
})

app.post('/api/users', zValidator('json', CreateUserSchema), (c) => {
  const data = c.req.valid('json') // 类型完全推断，无需手动标注
  // data.name: string, data.age: number, data.department: 'engineering' | ...
  return c.json({ success: true, user: data })
})

⚠️ 五、选型建议与避坑指南

5.1 选型决策树

根据你的项目需求，按以下优先级选择：

• ✅ **选 Zod：**如果你的项目使用 tRPC / React Hook Form / OpenAI SDK，或者团队已经熟悉 Zod 的 API，不要犹豫。生态是 Zod 最大的护城河。
• ✅ **选 Valibot：**如果你在构建 Serverless 函数、边缘计算应用、或对 Bundle 体积敏感的前端项目。Valibot 的 tree-shake 特性在这些场景中价值巨大。
• ✅ **选 ArkType：**如果你的团队追求极致的 DX，不介意较小的生态，且主要做后端验证（不需要表单库集成）。

5.2 常见踩坑点

⚠️ **警告：**以下是开发者在使用运行时验证时最常见的错误，务必注意。

踩坑 1：把验证 Schema 当类型用，不用 z.infer

// ❌ 错误：手动定义类型，和 Schema 分离，容易不一致
interface User {
  name: string
  age: number
}
const UserSchema = z.object({ name: z.string(), age: z.number() })
// 如果 Schema 加了字段但忘了更新 interface，编译通过但运行时会出问题

// ✅ 正确：从 Schema 推断类型，单一数据源
const UserSchema = z.object({ name: z.string(), age: z.number() })
type User = z.infer<typeof UserSchema>
// 修改 Schema 后类型自动更新

踩坑 2：忘记处理 .optional() 的嵌套情况

// ❌ 错误：address 可选但 city 必填，容易漏写
const schema = z.object({
  address: z.object({ city: z.string() }).optional()
})
// 如果 address 为 undefined，schema.address.city 不会报错
// 但访问 schema.data.address.city 会运行时崩溃

// ✅ 正确：使用嵌套 optional 或 refine 做条件验证
const schema = z.object({
  address: z.object({
    city: z.string(),
    zipCode: z.string().regex(/^\d{6}$/)
  }).optional()
}).refine(
  data => !data.address || data.address.zipCode,
  { message: '如果提供地址，邮编不能为空' }
)

踩坑 3：在热路径上反复创建 Schema

// ❌ 错误：在每次请求中创建新 Schema（Zod 内部有大量对象分配）
app.post('/api/data', (req, res) => {
  const schema = z.object({ /* ... */ }) // 每次请求都创建
  const result = schema.safeParse(req.body)
})

// ✅ 正确：在模块顶层定义 Schema，请求处理中只做 parse
const DataSchema = z.object({ /* ... */ })

app.post('/api/data', (req, res) => {
  const result = DataSchema.safeParse(req.body) // 复用已定义的 Schema
})

5.3 能否混合使用？

一个合理的策略是：在前端用 Valibot（体积小），在后端用 Zod（生态好）。由于两者都输出标准的 TypeScript 类型，你可以共享 interface / type 定义，只需要分别维护 Schema。但这会增加维护成本，建议仅在对体积有严格要求的场景下考虑。

💡 总结

2026 年的 TypeScript 运行时验证已经是一个成熟的领域。三款框架各有所长：

• 🔧 Zod — 生态最完善、文档最全、社区最大，是大多数项目的默认选择。适合需要 tRPC、React Hook Form、OpenAI SDK 集成的项目。
• 🔧 Valibot — 体积最小、性能优秀，tree-shake 设计理念领先。适合 Serverless、边缘计算、Bundle 敏感的前端项目。
• 🔧 ArkType — 语法最接近原生 TypeScript，解析性能最强。适合追求极致 DX 的后端项目和探索性开发。

如果你是新项目、没有特殊约束，从 Zod 开始是最安全的选择。当你遇到 bundle 体积瓶颈或性能问题时，再迁移到 Valibot 也不迟——它们的 API 设计理念相似，迁移成本可控。

📌 记住：最好的验证库是你团队能坚持使用的那个。运行时验证的价值不在于用了哪个库，而在于你是否在每一个数据边界都做了验证。