面向库作者

// 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 集成。相反，可以查看 Standard 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 版本的“永久链接”。这些将永远可用。

🌐 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/v4/core" 用于 Zod 4 核心包 ✅

你通常不应该从其他路径导入。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/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 扩展的 $ 前缀子类。Classic 和 Mini 子类的内部实现是相同的；它们唯一的区别在于实现了哪些辅助方法。

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

🌐 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 的 schema，请检查 "_zod" 属性。此属性仅在 Zod 4 的 schema 上定义。

🌐 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 | z4.$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 Core 页面。

🌐 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 extends z4.$ZodObject>(schema: T) {
  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