Zod系列 - 安装与版本说明

这节学什么

上一节建立了认知，这一节我们动手：把 Zod 装进项目、确认装的是哪个版本、搞清楚 v3 和 v4 到底什么关系，最后把第一个 schema 逐行讲透。学完你就能在自己的项目里真正跑起来。

一、先安装 Zod

1. 安装最新版（推荐，就是 v4）

现在默认安装的就是稳定的 v4。在项目根目录的终端里执行：

npm install zod

如果你想明确指定要 v4，也可以写成：

npm install zod@^4.0.0

2. 用其他包管理器

不同项目用的包管理器可能不同，命令对照如下，效果一样：

pnpm add zodyarn add zodbun add zod

3. 如果老项目需要 v3

有些旧项目还停在 v3，想安装 v3 就指定大版本号：

npm install zod@^3

二、确认自己装的是哪个版本

装完后，用下面的命令查看当前实际安装的版本：

npm ls zod

它会打印出类似 zod@4.6.0 的信息，前面的数字就是版本号。你也可以打开项目里的 package.json，在 dependencies 里看到 zod 对应的版本范围。

[!NOTE]怎么看版本号？版本号是三个数字，比如 4.6.0。第一位是大版本，大版本变化通常意味着有破坏性改动，所以 v3 升到 v4 要特别留意；后面两位是小版本和补丁，一般向后兼容。

三、v3 和 v4 是什么关系

你可能会在网上看到两种写法，先别慌，我们理清楚。

1. 简单的时间线

• • v3 在 2021 年 5 月发布，用了很多年，资料非常多
• • v4 经过约一年开发后稳定发布，是现在的主流版本，本系列就基于 v4
• • 最新的 v4 还在持续更新小版本

2. v4 主要进步在哪

官方强调 v4 更快、更省、编译更轻松，几个关键数字感受一下：

对你来说最直观的好处是：程序跑起来校验更快、打包体积更小、编辑器里的类型提示更流畅。

3. 新手要知道的几个写法差异

好消息是：最常用的核心写法，v3 和 v4 完全一样。

 比如 z.string()、z.object()、z.array()、parse、safeParse、z.infer，两版通用。你需要留意的主要是下面两处。

差异一：字符串格式改成了顶层函数

v4 里，邮箱、网址这类「字符串格式」推荐直接用 z 上的顶层函数，

旧的链式写法还能用但已经废弃：

import { z } from 'zod'// v4 推荐写法：顶层函数const emailSchema = z.email()// v3 的老写法，v4 仍可运行但已废弃，未来会移除const oldEmailSchema = z.string().email()

差异二：自定义错误统一用 error 参数

v4 把各种错误定制方式统一成了一个 error 参数，

旧的 message 还能用但已废弃：

// v4 推荐写法z.string().min(5, { error: '长度不能少于 5 个字符' })// v3 老写法，v4 仍可运行但已废弃z.string().min(5, { message: '长度不能少于 5 个字符' })

这两处你现在只要「眼熟」就行，等学到对应章节会专门细讲。本系列一律用 v4 的新写法，你照着写不会错。

4. 了解一下 zod/mini（暂时不用）

v4 还新增了一个叫 zod/mini 的版本，它的函数式写法更利于「按需打包」，能把体积压得更小，适合对包体积极度敏感的项目。新手阶段用普通的 zod 就好，这里只是让你以后看到这个词不陌生。

四、第一个 schema，逐行讲透

现在写一个完整、能运行的文件，我把每一行都拆开讲。

1. 完整代码

// 第 1 步：从 zod 导入 z，所有能力都从它开始import { z } from 'zod'// 第 2 步：用 z.object 定义一个「用户」schemaconst UserSchema = z.object({  name: z.string(), // name 必须是字符串  age: z.number(), // age 必须是数字})// 第 3 步：用 parse 检查一份真实数据const user = UserSchema.parse({ name: '刘笑', age: 18 })// 第 4 步：用 z.infer 自动得到 TypeScript 类型type User = z.infer<typeof UserSchema>// 第 5 步：之后声明变量就能用这个类型，编辑器会自动检查const another: User = { name: '小明', age: 20 }

2. 逐行理解

第 1 步，导入 z： 你可以把 z 理解成一个装满各种工具的工具箱，造字符串模板用 z.string()、造对象模板用 z.object()，都从它这里取。

第 2 步，定义 schema：z.object({...}) 表示「我要的数据是一个对象」，里面的每个字段再分别说明类型。这里规定了 name 是字符串、age 是数字。这个 schema 就是你的数据模板。

第 3 步，parse 检查： 把真实数据交给 UserSchema.parse(...)，它会对照模板逐项检查。合格就把数据返回给你，存进 user；不合格就立刻抛出错误，把问题拦在门外。

第 4 步，infer 推断类型：z.infer<typeof UserSchema> 会让 TypeScript 自动推导出 { name: string; age: number } 这个类型，你不用手写第二遍。

第 5 步，复用类型： 有了 User 类型，以后声明变量标注它，一旦字段写错或漏写，编辑器立刻提示。

3. 一个关键认知：schema 是「值」，不是「类型」

新手容易混淆，这里点一下：

UserSchema 是一个真实存在的 JavaScript 对象，运行时真的会执行检查；

而 type User 只在编译期存在，运行时会被擦除。

正因为有了「值」这个层面的 schema，Zod 才能补上 TypeScript 管不到的运行时缺口——这正好呼应上一节讲的核心问题。

五、动手验证一下

光看不练记不住，建议你在项目里建一个临时文件，把上面的代码粘进去，然后故意把 age 改成字符串 '十八'，再运行 parse，亲眼看看报错信息。改回数字后又恢复正常，这一动手，你对「运行时校验」的体感会立刻清晰很多。

速查表

小结

• • 用 npm install zod 安装的就是稳定的 v4，用 npm ls zod 确认版本
• • v4 比 v3 更快、包更小、类型编译更轻松，但核心写法两版一致
• • 新手重点记住两处新写法：字符串格式用 z.email() 等顶层函数、错误定制用 error 参数
• • 一个 schema 是运行时真实存在的值，z.infer 得到的类型只在编译期存在
• • 建议亲手改坏数据再看报错，建立运行时校验的体感