Valibot

一个轻量级、模块化、完整支持 tree-shaking 的 TypeScript Schema 校验库，以极小包体积和函数式 pipeline 架构著称，是新一代 schema 校验方案的代表。

技术简介说明

Valibot 是一个专为 TypeScript 设计的轻量级 Schema 校验库，由 Fabian Hiller 于 2023 年作为学士论文课题创建。它的核心创新在于模块化架构——整个库由数百个独立的小函数组成，每个函数负责单一职责，使得打包工具可以完整地进行 tree-shaking，最终打包体积可低至 1 KB 以下（取决于使用的 Schema 复杂度）。相比之下，Zod 约 12–15 KB，Yup 约 18–30 KB。

Valibot 采用了与传统链式 API 不同的 pipeline 函数式设计。开发者通过 v.pipe(value, v.string(), v.minLength(3)) 的方式组合校验规则，而非链式调用。这种设计不仅是风格差异，更是 tree-shaking 能生效的根本原因——每个函数独立导入，未使用的函数在编译期被完全剔除。

进入 2025–2026 年，Valibot 已成长为一个成熟的生产级方案。v1.0 稳定版于 2025 年初发布，npm 周下载量突破 1,000 万，GitHub star 数达到 8.4k。同时，Fabian Hiller 主导发起了 Standard Schema 互操作协议（联合 Zod 等库），并创建了 Formisch——基于 Valibot 的下一代表单库，标志着 Valibot 生态的日趋完善。

基本信息

• 官网：https://valibot.dev
• GitHub：https://github.com/open-circle/valibot（原 fabian-hiller/valibot，已迁移至 open-circle 组织）
• License：MIT
• 最新版本：1.4.0（2026-05-05 发布）
• 主要维护者：Fabian Hiller（fabian-hiller），Standard Schema 协议发起人，Formisch 作者
• GitHub Stars：~8,400（2026 年初）
• npm 周下载量：~1,000 万+（2026 年，Snyk 数据）
• 首次发布：2023 年（起源于 Fabian Hiller 的学士论文）
• 语言：TypeScript（原生，从零设计）
• 运行环境：浏览器 + Node.js + 边缘函数（Cloudflare Workers 等）

快速上手

安装

# npm
npm install valibot
 
# yarn
yarn add valibot
 
# pnpm
pnpm add valibot
 
# bun
bun add valibot

提示：Valibot 完整支持 tree-shaking，只需按需导入使用的函数即可，无需额外配置。支持 ESM 和 CJS 双格式，也发布在 JSR（@valibot/valibot）。

基础配置

Valibot 是零配置的纯函数库，安装后直接按需导入使用：

import * as v from 'valibot'

如果项目使用了 Strict 模式，Valibot 的所有函数都完整支持 TypeScript strict mode，无需额外 tsconfig.json 配置。

最小示例

import * as v from 'valibot'
 
// 定义 Schema
const LoginSchema = v.object({
  email: v.pipe(v.string(), v.email('请输入有效的邮箱')),
  password: v.pipe(v.string(), v.minLength(8, '密码至少 8 位')),
})
 
// 校验数据
const result = v.safeParse(LoginSchema, {
  email: '[email protected]',
  password: '12345678',
})
 
if (result.success) {
  console.log(result.output)
  // { email: '[email protected]', password: '12345678' }
} else {
  console.log(result.issues)
  // [{ message: '...', input: ..., path: ... }]
}
 
// 类型推断
type Login = v.InferOutput<typeof LoginSchema>
// { email: string; password: string }

核心概念与架构

核心概念

1. Schema：Valibot 中每个 Schema 都是一个独立的函数（如 v.string()、v.number()），返回一个描述数据结构的 Schema 对象。
2. Pipe（管道）：v.pipe(value, validation1, validation2, ...) 是 Valibot 的核心抽象，将多个验证动作串联执行。每个动作是独立的函数，这是 tree-shaking 的基础。
3. Validation / Action：校验动作是独立的小函数（如 v.minLength()、v.email()、v.minValue()），每个只负责一个校验规则。
4. Transform：在 pipe 中插入数据转换步骤（如 v.transform()），将输入值转换为另一种类型。
5. safeParse vs parse：parse() 失败时抛出异常；safeParse() 返回 { success, output, issues } 结构体，推荐使用。
6. InferOutput / InferInput：v.InferOutput<typeof Schema> 推断校验后输出类型；v.InferInput<typeof Schema> 推断输入类型（考虑可选字段、transform 等场景）。
7. Async Schema：通过 v.pipeAsync() 和 v.safeParseAsync() 支持异步校验（如远程接口验证）。

架构设计

┌──────────────────────────────────────────────────────────┐
│                      用户代码层                            │
│   v.pipe(v.string(), v.email(), v.minLength(5))          │
└─────────────┬────────────────────────────────────────────┘
              │
              ▼
┌──────────────────────────────────────────────────────────┐
│                  Schema 定义层（纯函数）                   │
│   每个 Schema / Action 都是独立可 tree-shake 的函数        │
│   string() | number() | email() | minLength() | ...      │
└─────────────┬────────────────────────────────────────────┘
              │
              ▼
┌──────────────────────────────────────────────────────────┐
│                   校验执行引擎                              │
│   parse() / safeParse() / safeParseAsync()                │
│   按 pipe 顺序逐个执行 action，遇到错误立即收集并继续       │
│   （可配置 abortEarly）                                    │
└─────────────┬────────────────────────────────────────────┘
              │
              ▼
┌──────────────────────────────────────────────────────────┐
│                    结果输出                                 │
│   成功：{ success: true, output: T }                      │
│   失败：{ success: false, issues: Issue[] }               │
└──────────────────────────────────────────────────────────┘

Valibot 的每个函数在编译期都是独立的模块引用，现代打包工具（Vite / Rollup / esbuild）在构建时可以精确剔除未使用的函数，实现 按需打包、零冗余。这是与 Zod / Yup 的「全量打包」架构的本质区别。

核心特性

• 极致 Tree-shaking：核心特性。库由数百个独立小函数组成，只有实际使用的函数会被打包，典型 Schema 打包体积 < 2 KB（gzip）。
• Pipeline 函数式 API：v.pipe(value, action1, action2) 的函数式组合模式，语义清晰，每个函数都可独立导入和测试。
• 完整 TypeScript 支持：从零为 TypeScript 设计，InferOutput 和 InferInput 可精确推断包括可选字段、默认值、transform 在内的复杂类型。
• Schema 序列化：Valibot Schema 可以被序列化为 JSON（通过 @valibot/to-json-schema 或 valibot-serialize），支持跨端共享 Schema 定义。
• 异步校验：pipeAsync() + safeParseAsync() 原生支持异步 action，无需额外封装。
• 丰富的内置 Action：string、number、boolean、date、array、object、tuple、union、intersect、enum、literal、nullable、optional、nullish、transform、 Brand 等 50+ 内置 action。
• Brand 类型：v.brand(schema, 'BrandName') 创建 branded type，在类型层面区分不同语义的同类型值（如 UserId vs OrderId 都是 string 但不可互换）。
• Coercion / Transform：v.pipe(v.string(), v.transform(Number)) 可在 pipe 中插入类型转换，无需像 Yup 那样依赖隐式 cast。
• Standard Schema 兼容：Valibot 是 Standard Schema 协议的发起成员，支持跨库互操作。
• 边缘运行时友好：极小包体积使其成为 Cloudflare Workers、Deno Deploy、Vercel Edge Functions 等边缘计算场景的首选校验库。
• 零依赖：整个库无外部运行时依赖，减少供应链安全风险。

生态图

核心生态

┌──────────────────────────────────────────────────────────┐
│                    Valibot 核心生态                        │
│                                                          │
│  @valibot/to-json-schema  — Valibot → JSON Schema 转换   │
│  valibot-serialize         — Schema 序列化/反序列化        │
│  Formisch                  — 基于 Valibot 的下一代表单库   │
│  Standard Schema           — 跨库互操作协议（联合 Zod）    │
└──────────────────────────────────────────────────────────┘
                         │
┌──────────────────────────────────────────────────────────┐
│                  框架集成                                   │
│  React Hook Form（官方 resolver）                          │
│  TanStack Form                                            │
│  SolidJS（通过 Formisch）                                  │
│  Svelte / Vue（社区集成）                                  │
└──────────────────────────────────────────────────────────┘
                         │
┌──────────────────────────────────────────────────────────┐
│                  社区工具                                   │
│  valibot-codegen          — Schema 代码生成                │
│  @modular-forms/solid     — SolidJS 表单集成               │
│  valibot-swagger          — Valibot → Swagger 文档生成     │
└──────────────────────────────────────────────────────────┘

关键生态项目

适用场景

• 包体积极度敏感的场景（最佳场景）：边缘函数（Cloudflare Workers、Vercel Edge）、嵌入式 widget、移动端 H5、Chrome 扩展等对 bundle size 有严苛要求的场景，Valibot 是无可争议的最佳选择。
• TypeScript-first 新项目：从零为 TS 设计，InferOutput 和 InferInput 类型推断精确，配合 branded type 可实现类型安全的领域建模。
• 需要 Schema 序列化 / 跨端共享的场景：Valibot Schema 可序列化为 JSON，在服务端和客户端之间传递 Schema 定义，支持从 Schema 生成 JSON Schema / OpenAPI 文档。
• 高吞吐 API 校验：Node.js 后端每秒处理大量校验请求时，Valibot 的性能优于 Zod 和 Yup，且冷启动更快（包体积小 → 加载快）。
• 函数式编程风格偏好：Pipeline API 天然契合函数式编程范式，容易与 fp-ts、Effect 等函数式库配合使用。
• 需要 Schema → 文档自动生成的场景：通过 @valibot/to-json-schema 可将 Valibot Schema 转为 JSON Schema，进而生成 OpenAPI / Swagger 文档。
• 现代表单集成（React Hook Form / TanStack Form）：React Hook Form 和 TanStack Form 均有官方 Valibot resolver，集成体验与 Zod 相当。

开发与工程化

开发流程

1. Schema 定义：使用 pipeline 风格定义 Schema，每个字段用 v.pipe() 串联校验规则。
2. 类型推断：通过 InferOutput / InferInput 从 Schema 自动推导类型，避免手动维护重复类型定义。
3. 校验执行：在业务层调用 safeParse() 或 safeParseAsync() 进行校验。
4. 错误处理：统一处理 issues 数组，映射为 UI 层所需的错误格式。
5. 测试：对关键 Schema 编写 safeParse 测试，覆盖正常值和各类非法输入。

构建部署

Valibot 天然支持现代打包工具，无需特殊配置。在 Vite、Rollup、esbuild、Webpack 5+ 中均可完美 tree-shake。

// vite.config.ts — 无需特殊配置
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
 
export default defineConfig({
  plugins: [react()],
})

验证 tree-shaking 效果：使用 npx vite-bundle-visualizer 或 Rollup 的 --treemap 插件，可以直观看到只有实际导入的函数被打包。

CI/CD 集成

# GitHub Actions 示例
- name: Run tests
  run: pnpm test -- --testPathPattern=valibot
 
- name: Type check
  run: pnpm typecheck
 
- name: Check bundle size
  run: pnpm build && npx size-limit

最佳工程实践

• 统一导入风格：使用 import * as v from 'valibot' 或按需 import { pipe, string, email } from 'valibot'，保持团队一致。
• Schema 分层：基础类型 Schema（如 EmailSchema、PasswordSchema）放在 schemas/ 目录，业务 Schema 组合基础 Schema。
• 复用 pipe：常用校验组合可提取为自定义 pipe 函数，如 const emailPipe = () => [v.string(), v.email(), v.minLength(5)] as const。
• 错误消息国际化：每个 action 的第二个参数支持自定义消息，配合 i18n 框架动态注入。

性能与安全

性能特点

• 包体积：典型 Schema 打包后 < 2 KB（gzip），是 Zod 的 1/10、Yup 的 1/15。在同等功能下是所有主流校验库中最小的。
• 校验速度：在复杂 Schema 场景下，Valibot 的校验速度是 Zod 的 2–3 倍（来源：CoderFile.io 2026 基准测试）。
• 冷启动：极小的包体积意味着更快的冷启动时间，在边缘函数和 serverless 场景中优势显著。
• V8 优化：由于函数式、无状态的设计，V8 引擎可以更有效地对 Valibot 的校验路径进行 JIT 优化。

注意：在简单的循环校验基准测试中，Zod 可能因为 V8 对热路径的深度优化而表现更好。Valibot 的优势体现在冷启动和复杂 Schema 场景。

优化建议

• 按需导入：始终使用具名导入 import { pipe, string, email } from 'valibot'，而非 import * as v（虽然 * as v 也能 tree-shake，但具名导入更明确）。
• 避免不必要的 action：每个 action 都是独立函数，未使用的 action 不会被打包，但 pipe 中的冗余 action 会增加运行时开销。
• safeParse 优先：safeParse() 比 parse() 更适合生产代码，因为它不依赖异常控制流，性能更稳定。
• 批量校验：对数组数据使用 v.array(schema) 一次性校验，避免循环调用 safeParse()。

安全注意事项

• 零外部依赖：Valibot 没有任何运行时外部依赖，减少了供应链攻击风险。
• 类型安全：InferOutput 推断出的类型在运行时被 safeParse 保证，配合 branded type 可防止跨域类型混淆。
• 输入消毒：Valibot 只做格式校验，不处理 XSS / SQL 注入等安全问题。服务端校验后仍需配合参数化查询和输出转义。
• Schema 序列化安全：反序列化 Schema 时应验证来源，避免从不可信来源加载 Schema。

已知性能瓶颈

• 大量嵌套的 union / intersect Schema 在校验时有额外的类型匹配开销。
• pipeAsync() 中过多的串行异步 action 可能成为性能瓶颈，建议将独立的异步 action 改为并行执行。
• 极深嵌套对象（> 10 层）的 safeParse 有额外的递归开销，但实际场景中极少遇到。

技术对比

选型决策树

你的项目对包体积有严苛要求吗？
├── 是 → Valibot
└── 否 → 你的项目已使用 Formik 吗？
           ├── 是 → Yup（无缝集成）
           └── 否 → 你的项目是 TS-first 且不需要极致包体积？
                      ├── 是 → Zod（最大社区，最好 DX）
                      └── 否 → Valibot 或 Zod 均可

最佳实践

生产环境建议

1. 统一 Schema 定义风格

// schemas/user.ts
import * as v from 'valibot'
 
// 推荐：复用基础 pipe
const EmailPipe = [v.string(), v.email('请输入有效的邮箱')] as const
const PasswordPipe = [v.string(), v.minLength(8, '密码至少 8 位')] as const
 
export const CreateUserSchema = v.object({
  email: v.pipe(...EmailPipe),
  password: v.pipe(...PasswordPipe),
  name: v.pipe(v.string(), v.minLength(2, '姓名至少 2 个字符')),
})
 
export type CreateUserInput = v.InferInput<typeof CreateUserSchema>
export type CreateUserOutput = v.InferOutput<typeof CreateUserSchema>

2. Branded Type 防止类型混淆

const UserIdSchema = v.pipe(v.string(), v.uuid(), v.brand('UserId'))
const OrderIdSchema = v.pipe(v.string(), v.uuid(), v.brand('OrderId'))
 
type UserId = v.InferOutput<typeof UserIdSchema>
type OrderId = v.InferOutput<typeof OrderIdSchema>
 
// 类型安全：UserId 和 OrderId 虽然都是 string，但 TypeScript 层面不可互换
function getUser(id: UserId) { /* ... */ }
const orderId = v.parse(OrderIdSchema, '...')
getUser(orderId) // TypeScript 编译错误 ✅

3. 异步校验（如用户名查重）

const UsernameSchema = v.pipeAsync(
  v.string(),
  v.minLength(3, '用户名至少 3 个字符'),
  v.checkAsync(async (value) => {
    const res = await fetch(`/api/check-username?name=${value}`)
    const data = await res.json()
    return !data.exists
  }, '该用户名已被注册')
)
 
const result = await v.safeParseAsync(UsernameSchema, 'newuser')

4. 自定义错误消息国际化

import * as v from 'valibot'
 
// 封装 i18n 友好的校验函数
function minLength(min: number, field: string) {
  return v.minLength(min, `${field} 至少需要 ${min} 个字符`)
}
 
const schema = v.object({
  name: v.pipe(v.string(), minLength(2, '姓名')),
})

5. Transform 处理表单数据

// 表单提交后将字符串日期转换为 Date 对象
const EventSchema = v.object({
  title: v.pipe(v.string(), v.minLength(1)),
  date: v.pipe(
    v.string(),
    v.transform((value) => new Date(value)),
  ),
})
 
const result = v.parse(EventSchema, { title: 'Meeting', date: '2026-07-01' })
// result.date 是 Date 实例

常见陷阱

• parse vs safeParse：parse 失败时抛出异常，在控制流中应优先使用 safeParse，避免用异常处理业务逻辑。
• InferInput vs InferOutput：两者在存在 transform、optional、default 时结果不同。InferInput 是校验前的输入类型（如 string | undefined），InferOutput 是校验后的输出类型（如 string，含默认值）。混淆两者会导致类型 bug。
• Pipeline 中的顺序：pipe 中的 action 按顺序执行，类型转换 transform 应放在类型相关校验之后（先 string() 再 transform(Number)）。
• v.optional 的默认值：v.optional(schema, default) 只在输入为 undefined 时使用默认值，null 不会触发默认值。对 null 需用 v.nullish()。
• 数组校验：v.array(schema) 默认接受空数组，必填数组需额外加 v.minLength(arraySchema, 1)。
• Tree-shaking 验证：如果打包后体积异常大，检查是否意外导入了未使用的函数，或打包工具未正确配置 tree-shaking（如 sideEffects: true 的旧配置）。

技术局限与边界

已知限制

1. Pipeline API 学习曲线：对于习惯链式 API（Zod / Yup）的开发者，v.pipe(value, action1, action2) 的函数式风格需要适应期。
2. 社区规模仍在增长期：相比 Zod 的 ~80k stars，Valibot 的 8.4k stars 意味着遇到问题时可参考的社区资源相对较少。
3. Formik 集成不够原生：Formik 的 validationSchema 只原生支持 Yup，Valibot 需要通过 adapter 或自定义 validate 函数集成，体验不如 Yup 顺滑。
4. 存量项目较少：Valibot 是 2023 年才发布的新库，在生产环境中的验证时间和案例积累不如 Yup / Zod。
5. 部分高级类型推断限制：极复杂的条件 Schema（如 variant 嵌套多层）在 TypeScript 类型推断上可能遇到 TS 编译器限制。
6. 文档仍在完善：虽然官方文档 valibot.dev 质量不错，但部分高级特性的示例和最佳实践还不够全面。

不适用场景

• 已有 Formik + Yup 技术栈的维护项目：迁移到 Valibot 需要重写所有 Schema，且 Formik 集成体验不如 Yup，ROI 不高。
• 团队完全习惯链式 API 且无包体积痛点：如果团队对 Zod 已很熟练且项目包体积不是问题，切换到 Valibot 的学习成本可能超过收益。
• 需要大量复杂递归 Schema：Valibot 对递归 Schema（如树形结构）的支持不如 Zod 成熟，需要手动处理。
• 需要与 tRPC 深度集成：tRPC 官方使用 Zod，Valibot 集成需要额外适配工作。

迁移注意事项

• 从 Zod 迁移到 Valibot：API 风格差异较大（链式 vs pipeline），需要全面改写。但语义一一映射，迁移路径清晰。建议逐模块迁移，先对包体积敏感的模块下手。
• 从 Yup 迁移到 Valibot：差异最大，Yup 的 cast()、when() 等概念需要重新理解。建议在新模块中使用 Valibot，旧模块保持 Yup，逐步替换。
• 共存策略：Valibot 支持 Standard Schema 协议，可与 Zod 在同一项目中通过 Standard Schema 接口共存，便于渐进迁移。

学习资源

官方文档

• Valibot 官方文档（valibot.dev） — 最权威的学习入口，包含完整 API 参考和指南
• Valibot 官方比较指南 — 与 Zod / Yup 等库的官方对比
• Valibot v1.1 Release Notes — 最新版本的变更说明
• Valibot v1 RC 发布博客 — v1 里程碑的设计决策说明
• GitHub 仓库 — 源码、Issue 和讨论
• JSR 包页面 — Deno / JSR 生态的安装方式

教程

• Valibot: Ultra-Lightweight & Type-Safe Schema Validation（Mamezou Tech） — 详细的入门教程，含与 Zod 对比
• JavaScript schema library from the Future（DEV Community） — Valibot 在 2025 年 schema 库格局中的定位
• How Valibot has evolved this year（官方博客） — Valibot 年度演进总结

社区资源

• GitHub Discussions — 功能讨论、Q&A
• DevTools.fm Episode #163: Fabian Hiller — Valibot 创建者访谈（2026-02）
• Valibot, Standard Schema and Formisch（YouTube） — Fabian Hiller 的演讲
• Zod VS Valibot: JS/TS Validator Battle!（YouTube） — 视频对比，含代码示例
• Zod vs Yup vs Valibot 2026（PkgPulse） — 2026 年最新对比文章

2026 年现状

最新版本

• 当前稳定版：1.4.0（2026-05-05 发布）
• 发布节奏：2025 年发布了 v1.0（里程碑稳定版）、v1.1，2026 年持续迭代至 1.4.0，保持每月 1–2 个小版本的发布节奏。

发展趋势

• 快速增长期：Valibot 正处于高速增长阶段，npm 周下载量从 2024 年初的 ~30 万增长到 2026 年的 ~1,000 万+，增长曲线陡峭。
• Standard Schema 推动互操作：Fabian Hiller 主导的 Standard Schema 协议已获得 Zod、ArkType 等主流库的支持，Valibot 作为发起成员在其中扮演重要角色。
• Formisch 生态拓展：基于 Valibot 的下一代表单库 Formisch 正在积极开发中，支持 SolidJS、React 等框架，目标是提供比 Formik / React Hook Form 更原生的 Schema 驱动表单体验。
• 边缘计算趋势的受益者：随着 Cloudflare Workers、Vercel Edge、Deno Deploy 等边缘计算平台的普及，Valibot 的极小包体积成为核心竞争力。

社区活跃度

未来路线图

• v1.x 持续迭代：当前以稳定化和功能完善为主，持续增加新的 action 和优化 TypeScript 推断。
• Formisch 正式发布：预计 2026 年内发布稳定版，成为 Valibot 生态的重要一环。
• Standard Schema v1 规范：推动跨库互操作协议的标准化，让 Valibot Schema 可以在任何支持 Standard Schema 的库中直接使用。
• 代码生成工具：社区已在探索从 Valibot Schema 生成 TypeScript 类型、JSON Schema、OpenAPI 文档的工具链（如 valibot-serialize、@valibot/to-json-schema）。
• Deno 生态支持：Valibot 已发布在 JSR（@valibot/valibot），对 Deno 2.0+ 生态的支持将持续加强。

综合评价

Valibot 是 Schema 校验领域的一股清流——它用模块化、函数式的设计重新定义了校验库的架构，实现了真正的 tree-shaking 和极致包体积。在 2026 年的技术格局下，Valibot 是包体积敏感场景（边缘函数、嵌入式 widget）的无可争议的首选，也是 TypeScript-first 新项目的优秀选项。随着 Standard Schema 协议的推广和 Formisch 生态的成熟，Valibot 有望在未来 2–3 年内成为与 Zod 并驾齐驱的主流校验方案。对于新项目，尤其是包体积和性能敏感的项目，强烈推荐优先考虑 Valibot。