# @cabloy/zod 中文文档

规范地址：https://npmcn.com/package/%40cabloy/zod/

版本：4\.3\.8
npm 元数据更新时间：2026-06-26T03:20:43.313Z
中文译文更新时间：2026-11-08T23:11:17.470Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cabloy/zod
原文对照：https://npmcn.com/package/%40cabloy/zod/?lang=original
项目主页：https://zod.dev/
源码仓库：https://github.com/colinhacks/zod

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.4 MB，701 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-04-13T03:03:19.381Z
- 最新版本发布：2026-06-26T03:20:43.179Z
- 近 30 天下载量：5449（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

TypeScript- First schema 声明和验证库,带有静态类型推论

## 安装

```sh
npm install @cabloy/zod
```

也可以使用：`pnpm add @cabloy/zod`、`yarn add @cabloy/zod`、`bun add @cabloy/zod`

## README

![Zod logo](https://npmcn.com/package/%40cabloy/zod/logo.svg)

# 佐德语Name

TypeScript- first schema 验证并采用静态类型推论  
以 [@colinhacks (英语)](https://x.com/colinhacks)

  

[![Zod CI status](https://github.com/colinhacks/zod/actions/workflows/test.yml/badge.svg?event=push&branch=main)](https://github.com/colinhacks/zod/actions?query=branch%3Amain) [![License](https://img.shields.io/github/license/colinhacks/zod)](https://opensource.org/licenses/MIT) [![npm](https://img.shields.io/npm/dw/zod.svg)](https://www.npmjs.com/package/zod) [![discord server](https://img.shields.io/discord/893487829802418277?label=Discord&logo=discord&logoColor=white)](https://discord.gg/KaSRdyX2vc) [![stars](https://img.shields.io/github/stars/colinhacks/zod)](https://github.com/colinhacks/zod)

[文档](https://zod.dev/api)   二. 支助   [解析器](https://discord.gg/RcG33DQJdf)   二. 支助   [页:1](https://twitter.com/colinhacks)   二. 支助   [布鲁斯基](https://bsky.app/profile/zod.dev)  

  
  

## 赞助人:爵士乐

[![jazz logo](https://raw.githubusercontent.com/garden-co/jazz/938f6767e46cdfded60e50d99bf3b533f4809c68/homepage/homepage/public/Zod%20sponsor%20message.png)](https://jazz.tools/?utm_source=zod)  

学习更多关于 [专题赞助](mailto:sponsorship@colinhacks.com)

  
  
  

### [阅读文件 {}](https://zod.dev/api)

  
  

## 佐德是谁?

Zod是一个TypeScript-First验证库. 定义一个计划并分析一些数据。 你会得到一个强烈打字, 验证的结果.

```ts
import * as z from "zod";

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

// some untrusted data...
const input = {
  /* stuff */
};

// the parsed result is validated and type safe!
const data = User.parse(input);

// so you can use it with confidence :)
console.log(data.name);
```

  

## 特征

-   外部依赖性为零
-   在Node.js和所有现代浏览器中工作
-   小声: `2kb` 核心捆绑( gzip)
-   不可移动 API: 方法返回新实例
-   简洁界面
-   与TypeScript和普通JS合作
-   内建 JSON Schema 转换
-   广泛的生态系统

  

## 安装

```sh
npm install zod
```

  

## 基本用途

在你可以做其他事情之前,需要定义一个计划. 为了本指南的目的,我们将使用简单的对象计划.

```ts
import * as z from "zod";

const Player = z.object({
  username: z.string(),
  xp: z.number(),
});
```

### 分析数据

考虑到Zod计划,使用 `.parse` 以验证输入。 如果有效, Zod 返回强烈类型 _深克隆_ 输入.

```ts
Player.parse({ username: "billie", xp: 100 });
// => returns { username: "billie", xp: 100 }
```

**说明** -如果您的计划使用某种同步的 API 如 `async` [改进](https://zod.dev/api#refinements) 或者说 [变换](https://zod.dev/api#transforms),你将需要使用 `.parseAsync()` 方法代替.

```ts
const schema = z.string().refine(async (val) => val.length <= 8);

await schema.parseAsync("hello");
// => "hello"
```

### 处理错误

当验证失败时 `.parse()` 方法将丢出一个 `ZodError` 实例中包含关于验证问题的颗粒信息.

```ts
try {
  Player.parse({ username: 42, xp: "100" });
} catch (err) {
  if (err instanceof z.ZodError) {
    err.issues;
    /* [
      {
        expected: 'string',
        code: 'invalid_type',
        path: [ 'username' ],
        message: 'Invalid input: expected string'
      },
      {
        expected: 'number',
        code: 'invalid_type',
        path: [ 'xp' ],
        message: 'Invalid input: expected number'
      }
    ] */
  }
}
```

为了避免 `try/catch` 块,您可以使用 `.safeParse()` 方法以获取包含成功解析数据或a的纯结果对象 `ZodError`。结果类型是 [受歧视的工会](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions)来方便地处理这两个案子.

```ts
const result = Player.safeParse({ username: 42, xp: "100" });
if (!result.success) {
  result.error; // ZodError instance
} else {
  result.data; // { username: string; xp: number }
}
```

**说明** -如果您的计划使用某种同步的 API 如 `async` [改进](https://zod.dev/api#refinements) 或者说 [变换](https://zod.dev/api#transforms),你将需要使用 `.safeParseAsync()` 方法代替.

```ts
const schema = z.string().refine(async (val) => val.length <= 8);

await schema.safeParseAsync("hello");
// => { success: true; data: "hello" }
```

### 推断类型

Zod从你的计划定义推断出一种静态类型. 您可以用 `z.infer<>` 有用,随便你用.

```ts
const Player = z.object({
  username: z.string(),
  xp: z.number(),
});

// extract the inferred type
type Player = z.infer<typeof Player>;

// use it in your code
const player: Player = { username: "billie", xp: 100 };
```

在某些情况下,一个计划的输入和输出类型可能有所不同. 例如 `.transform()` API可以将输入从一种类型转换到另一种类型. 在这种情况下,您可以独立提取输入和输出类型:

```ts
const mySchema = z.string().transform((val) => val.length);

type MySchemaIn = z.input<typeof mySchema>;
// => string

type MySchemaOut = z.output<typeof mySchema>; // equivalent to z.infer<typeof mySchema>
// number
```

## 常见问题

### @cabloy/zod 是什么？

TypeScript- First schema 声明和验证库,带有静态类型推论

### 如何安装 @cabloy/zod？

在项目目录运行 npm install @cabloy/zod，或使用 pnpm add / yarn add / bun add。

### @cabloy/zod 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cabloy/zod 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cabloy/zod 可以商用吗？

@cabloy/zod 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cabloy/zod 的下载量有多少？

根据 npm 官方下载统计，@cabloy/zod 在 2026/10/09 – 2026/11/07 这 30 天内被下载 5,449 次，日均约 182 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cabloy/zod 还在维护吗？

最新版本 4\.3\.8 发布于 2026/06/26（4 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/04/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。