面向库作者

// package.json
{
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  }
}

本页面主要供在 Zod 上构建工具的库作者使用。

¥This page is primarily intended for consumption by library authors who are building tooling on top of Zod.

我需要依赖 Zod 吗？

¥Do I need to depend on Zod?

首先，请确保你需要依赖 Zod。

¥First things first, make sure you need to depend on Zod at all.

如果你正在构建一个接受用户定义模式来执行黑盒验证的库，则可能不需要专门与 Zod 集成。请参考 标准 Schema。它是 TypeScript 生态系统中大多数流行验证库（参见 完整列表）都实现的共享接口，包括 Zod。

¥If you're building a library that accepts user-defined schemas to perform black-box validation, you may not need to integrate with Zod specifically. Instead look into Standard Schema. It's a shared interface implemented by most popular validation libraries in the TypeScript ecosystem (see the full list), including Zod.

如果你接受用户定义的模式并将其视为 "黑盒" 验证器，则此规范非常有效。对于任何兼容的库，你可以提取推断的输入/输出类型，验证输入并返回标准化错误。

¥This spec works great if you accept user-defined schemas and treat them like "black box" validators. Given any compliant library, you can extract inferred input/output types, validate inputs, and get back a standardized error.

如果你需要 Zod 的特定功能，请继续阅读。

¥If you need Zod specific functionality, read on.

如何配置对等依赖？

¥How to configure peer dependencies?

任何基于 Zod 构建的库都应在 "peerDependencies" 中包含 "zod"。这允许你的用户使用 "自带 Zod"。

¥Any library built on top of Zod should include "zod" in "peerDependencies". This lets your users "bring their own Zod".

// package.json
{
  // ...
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0" // the "zod/v4" subpath was added in 3.25.0
  }
}

在开发过程中，你需要满足自己的对等依赖要求，为此，请将 "zod" 也添加到你的 "devDependencies" 中。

¥During development, you need to meet your own peer dependency requirement, to do so, add "zod" to your "devDependencies" as well.

// package.json
{
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  },
  "devDependencies": {
    // generally, you should develop against the latest version of Zod
    "zod": "^3.25.0 || ^4.0.0"
  }
}

如何支持 Zod 4？

¥How to support Zod 4?

要支持 Zod 4，请将 "zod" 对等依赖的最低版本更新为 ^3.25.0 || ^4.0.0。

¥To support Zod 4, update the minimum version for your "zod" peer dependency to ^3.25.0 || ^4.0.0.

// package.json
{
  // ...
  "peerDependencies": {
    "zod": "^3.25.0 || ^4.0.0"
  }
}

从 v3.25.0 开始，Zod 4 核心包可在 "zod/v4/core" 子路径下使用。阅读 Zod 4 中的版本控制 文档，了解有关此版本控制方法的完整上下文。

¥Starting with v3.25.0, the Zod 4 core package is available at the "zod/v4/core" subpath. Read the Versioning in Zod 4 writeup for full context on this versioning approach.

import * as z4 from "zod/v4/core";

仅从这些子路径导入。将它们视为各自 Zod 版本的 "permalinks"。这些将永久可用。

¥Import from these subpaths only. Think of them like "permalinks" to their respective Zod versions. These will remain available forever.

• "zod/v3" 代表 Zod 3 ✅

  ¥"zod/v3" for Zod 3 ✅

• "zod/v4/core" 适用于 Zod 4 Core 软件包 ✅

  ¥"zod/v4/core" for the Zod 4 Core package ✅

通常情况下，你不应该从任何其他路径导入。Zod Core 库是一个共享库，它同时支持 Zod 4 Classic 和 Zod 4 Mini。通常，实现任何特定于其中一种或另一种的功能都是一个坏主意。请勿从以下子路径导入：

¥You generally shouldn't be importing from any other paths. The Zod Core library is a shared library that undergirds both Zod 4 Classic and Zod 4 Mini. It's generally a bad idea to implement any functionality that is specific to one or the other. Do not import from these subpaths:

• "zod" — ❌ 在 3.x 版本中，这会导出 Zod 3。在 4.x 版本中，这将导出 Zod 4。请使用永久链接。

  ¥"zod" — ❌ In 3.x releases, this exports Zod 3. In 4.x releases, this will export Zod 4. Use the permalinks instead.

• "zod/v4" 和 "zod/v4/mini" — ❌ 这些子路径分别是 Zod 4 Classic 和 Mini 的所在路径。如果你希望你的库能够同时兼容 Zod 和 Zod Mini，则应该基于 "zod/v4/core" 中定义的基类进行构建。如果你引用了 "zod/v4" 模块中的类，你的库将无法与 Zod Mini 兼容，反之亦然。极力避免这种做法。请改用 "zod/v4/core"，它会导出 Zod Classic 和 Zod Mini 扩展的以 $ 为前缀的子类。经典子类和迷你子类的内部结构相同；它们的区别仅在于它们实现的辅助方法。

  ¥"zod/v4" and "zod/v4/mini"— ❌ These subpaths are the homes of Zod 4 Classic and Mini, respectively. If you want your library to work with both Zod and Zod Mini, you should build against the base classes defined in "zod/v4/core". If you reference classes from the "zod/v4" module, your library will not work with Zod Mini, and vice versa. This is extremely discouraged. Use "zod/v4/core" instead, which exports the $-prefixed subclasses that are extended by Zod Classic and Zod Mini. The internals of the classic & mini subclasses are identical; they only differ in which helper methods they implement.

我需要发布一个新的主要版本吗？

¥Do I need to publish a new major version?

不，你不需要发布库的新主版本来支持 Zod 4（除非你放弃对 Zod 3 的支持，但我们不建议这样做）。

¥No, you should not need to publish a new major version of your library to support Zod 4 (unless you are dropping support for Zod 3, which isn't recommended).

你需要将对等依赖提升到 ^3.25.0，因此你的用户需要 npm upgrade zod。但在 zod@3.24 和 zod@3.25 之间，Zod 3 没有发生重大更改；事实上，没有任何代码更改。由于你的用户需要更改代码，因此我认为这不构成重大变更。我不建议发布新的主要版本。

¥You will need to bump your peer dependency to ^3.25.0, thus your users will need to npm upgrade zod. But there were no breaking changes made to Zod 3 between zod@3.24 and zod@3.25; in fact, there were no code changes whatsoever. As code changes will be required on the part of your users, I do not believe this constitutes a breaking change. I recommend against publishing a new major version.

如何同时支持 Zod 3 和 Zod 4？

¥How to support Zod 3 and Zod 4 simultaneously?

从 v3.25.0 开始，该包在各自的子路径中包含 Zod 3 和 Zod 4 的副本。这使得同时支持两个版本变得容易。

¥Starting in v3.25.0, the package contains copies of both Zod 3 and Zod 4 at their respective subpaths. This makes it easy to support both versions simultaneously.

import * as z3 from "zod/v3";
import * as z4 from "zod/v4/core";
 
type Schema = z3.ZodTypeAny | z4.$ZodType;
 
function acceptUserSchema(schema: z3.ZodTypeAny | z4.$ZodType) {
  // ...
}

要在运行时区分 Zod 3 和 Zod 4 的模式，请检查 "_zod" 属性。此属性仅在 Zod 4 模式中定义。

¥To differentiate between Zod 3 and Zod 4 schemas at runtime, check for the "_zod" property. This property is only defined on Zod 4 schemas.

import type * as z3 from "zod/v3";
import type * as z4 from "zod/v4/core";
 
declare const schema: z3.ZodTypeAny | v4.$ZodType;
 
if ("_zod" in schema) {
  schema._zod.def; // Zod 4 schema
} else {
  schema._def; // Zod 3 schema
}

如何同时支持 Zod 和 Zod Mini？

¥How to support Zod and Zod Mini simultaneously?

你的库代码应该只从 "zod/v4/core" 导入。此子包定义了 Zod 和 Zod Mini 之间共享的接口、类和实用程序。

¥Your library code should only import from "zod/v4/core". This sub-package defines the interfaces, classes, and utilities that are shared between Zod and Zod Mini.

// library code
import * as z4 from "zod/v4/core";
 
export function acceptObjectSchema<T extends z4.$ZodObject>(schema: T){
  // parse data
  z4.parse(schema, { /* somedata */});
  // inspect internals
  schema._zod.def.shape;
}

通过基于共享基接口构建，你可以同时可靠地支持这两个子包。此函数可以同时接受 Zod 和 Zod Mini 模式。

¥By building against the shared base interfaces, you can reliably support both sub-packages simultaneously. This function can accept both Zod and Zod Mini schemas.

// user code
import { acceptObjectSchema } from "your-library";
 
// Zod 4
import * as z from "zod";
acceptObjectSchema(z.object({ name: z.string() }));
 
// Zod 4 Mini
import * as zm from "zod/mini";
acceptObjectSchema(zm.object({ name: zm.string() }))

有关更多信息，请参阅 Zod 核心。

¥Refer to the Zod Core page for more information on the contents of the core sub-library.

如何接受用户定义的模式？

¥How to accept user-defined schemas?

接受用户定义的模式是任何基于 Zod 构建的库的基本操作。本节概述了执行此操作的最佳实践。

¥Accepting user-defined schemas is the a fundamental operation for any library built on Zod. This section outlines the best practices for doing so.

刚开始时，可​​能很容易编写一个接受 Zod 模式的函数，如下所示：

¥When starting out, it may be tempting to write a function that accepts a Zod schema like this:

import * as z4 from "zod/v4/core";
 
function inferSchema<T>(schema: z4.$ZodType<T>) {
  return schema;
}

这种方法是错误的，并且限制了 TypeScript 正确推断参数的能力。无论你传入什么，schema 的类型都将是 $ZodType 的实例。

¥This approach is incorrect, and limits TypeScript's ability to properly infer the argument. No matter what you pass in, the type of schema will be an instance of $ZodType.

inferSchema(z.string());
// => $ZodType<string>

这种方法会丢失类型信息，即输入实际上是哪个子类（在本例中为 ZodString）。这意味着你无法在 inferSchema 的结果上调用任何特定于字符串的方法，例如 .min()。相反，你的泛型参数应该扩展核心 Zod 模式接口：

¥This approach loses type information, namely which subclass the input actually is (in this case, ZodString). That means you can't call any string-specific methods like .min() on the result of inferSchema. Instead, your generic parameter should extend the core Zod schema interface:

function inferSchema<T extends z4.$ZodType>(schema: T) {
  return schema;
}
 
inferSchema(z.string());
// => ZodString ✅

要将输入模式限制为特定子类：

¥To constrain the input schema to a specific subclass:

 
import * as z4 from "zod/v4/core";
 
// only accepts object schemas
function inferSchema<T>(schema: z4.$ZodObject) {
  return schema;
}

要限制输入模式的推断输出类型：

¥To constrain the inferred output type of the input schema:

 
import * as z4 from "zod/v4/core";
 
// only accepts string schemas
function inferSchema<T extends z4.$ZodType<string>>(schema: T) {
  return schema;
}
 
inferSchema(z.string()); // ✅ 
 
inferSchema(z.number()); 
// ❌ The types of '_zod.output' are incompatible between these types. 
// // Type 'number' is not assignable to type 'string'

要使用模式解析数据，请使用顶层 z4.parse/z4.safeParse/z4.parseAsync/z4.safeParseAsync 函数。z4.$ZodType 子类本身没有方法。常用的解析方法由 Zod 和 Zod Mini 实现，但在 Zod Core 中不可用。

¥To parse data with the schema, use the top-level z4.parse/z4.safeParse/z4.parseAsync/z4.safeParseAsync functions. The z4.$ZodType subclass has no methods on it. The usual parsing methods are implemented by Zod and Zod Mini, but are not available in Zod Core.

function parseData<T extends z4.$ZodType>(data: unknown, schema: T): z4.output<T> {
  return z.parse(schema, data);
}
 
parseData("sup", z.string());
// => string