Zod Mini

Zod Mini 变体随着 Zod 4 的发布而推出。要尝试它：

🌐 Zod Mini variant was introduced with the release of Zod 4. To try it:

npm install zod@^4.0.0

导入方法：

🌐 To import it:

import * as z from "zod/mini";

Zod Mini 实现了与 zod 完全相同的功能，但使用的是 函数式、可摇树优化 的 API。如果你来自 zod，这意味着你通常会用 函数 来代替方法。

🌐 Zod Mini implements the exact same functionality as zod, but using a functional, tree-shakable API. If you're coming from zod, this means you generally will use functions in place of methods.

// regular Zod
const mySchema = z.string().optional().nullable();
 
// Zod Mini
const mySchema = z.nullable(z.optional(z.string()));

摇树优化

🌐 Tree-shaking

Tree-shaking 是现代打包工具用来从最终包中移除未使用代码的一种技术。它也被称为死代码消除。

🌐 Tree-shaking is a technique used by modern bundlers to remove unused code from the final bundle. It's also referred to as dead-code elimination.

在常规的 Zod 中，模式提供了一系列方便的方法来执行一些常见操作（例如在字符串模式上使用 .min()）。打包工具通常无法从你的包中移除（“tree-shake”）未使用的方法实现，但它们能够移除未使用的顶层函数。因此，Zod Mini 的 API 使用的函数比方法更多。

🌐 In regular Zod, schemas provide a range of convenience methods to perform some common operations (e.g. .min() on string schemas). Bundlers are generally not able to remove ("treeshake") unused method implementations from your bundle, but they are able to remove unused top-level functions. As such, the API of Zod Mini uses more functions than methods.

// regular Zod
z.string().min(5).max(10).trim()
 
// Zod Mini
z.string().check(z.minLength(5), z.maxLength(10), z.trim());

要大致了解打包体积的缩减，请参考以下简单脚本：

🌐 To give a general idea about the bundle size reduction, consider this simple script:

z.boolean().parse(true)

将其与 Zod 和 Zod Mini 打包会得到以下打包包大小。Zod Mini 可减少 64%。

🌐 Bundling this with Zod and Zod Mini results in the following bundle sizes. Zod Mini results in a 64% reduction.

使用稍微复杂一点的模式，其中涉及对象类型：

🌐 With a marginally more complex schema that involves object types:

const schema = z.object({ a: z.string(), b: z.number(), c: z.boolean() });
 
schema.parse({
  a: "asdf",
  b: 123,
  c: true,
});

这让你对所涉及的打包包大小有一个了解。仔细看看这些数字，并运行你自己的基准测试，以确定在你的使用情况下使用 Zod Mini 是否值得。

🌐 This gives you a sense of the bundle sizes involved. Look closely at these numbers and run your own benchmarks to determine if using Zod Mini is worth it for your use case.

何时（不）使用 Zod Mini

🌐 When (not) to use Zod Mini

一般来说，你可能应该使用常规 Zod，除非你对打包包大小有非常严格的限制。许多开发者过高估计了打包包大小对应用性能的重要性。实际上，在 Zod 规模（通常为 5-10kb）的打包包大小，只有在为农村或发展中地区网速较慢的用户优化前端打包包时才是一个值得关注的问题。

🌐 In general you should probably use regular Zod unless you have uncommonly strict constraints around bundle size. Many developers massively overestimate the importance of bundle size to application performance. In practice, bundle size on the scale of Zod (5-10kb typically) is only a meaningful concern when optimizing front-end bundles for a user base with slow mobile network connections in rural or developing areas.

让我们来看一下以下几点注意事项：

🌐 Let's run through some considerations:

DX

Zod Mini 的 API 更冗长且不易发现。与 Zod Mini 的顶层函数相比，Zod 的 API 方法更容易通过 Intellisense 发现和自动补全。无法通过链式 API 快速构建模式。（作为 Zod 的创建者：我花了很多时间设计 Zod Mini API，使其尽可能符合人机工程学，但我仍然强烈偏好标准的 Zod API。）

🌐 The API of Zod Mini is more verbose and less discoverable. The methods in Zod's API are much easier to discover & autocomplete through Intellisense than the top-level functions in Zod Mini. It isn't possible to quickly build a schema with chained APIs. (Speaking as the creator of Zod: I spent a lot of time designing the Zod Mini API to be as ergonomic as possible, but I still have a strong preference the standard Zod API.)

后端开发

🌐 Backend development

如果你在后端使用 Zod，那么 Zod 规模的包大小意义不大。即使在像 Lambda 这样的资源受限环境中，这也是成立的。这篇文章 基准测试了不同大小包的冷启动时间。以下是部分结果：

🌐 If you are using Zod on the backend, bundle size on the scale of Zod is not meaningful. This is true even in resource-constrained environments like Lambda. This post benchmarks cold start times with bundles of various sizes. Here is a subset of the results:

一个可忽略的 1kb 包的最小冷启动时间是 171ms。下一个测试的包大小是 128kb，只增加了 5ms。压缩后，整个常规 Zod 的包大小大约是 17kb，这将对应于启动时间增加 0.6ms。

🌐 The minimum cold start time for a negligible 1kb bundle is 171ms. The next bundle size tested is 128kb, which added only 5ms. When gzipped, the bundle size for the entirely of regular Zod is roughly 17kb, which would correspond to a 0.6ms increase in startup time.

网速

🌐 Internet speed

通常，到服务器（100-200ms）的往返时间将远远超过下载额外 10kb 所需的时间。只有在慢速 3G 连接（低于 1Mbps）上，下载额外 10kb 的时间才会变得更显著。如果你不是专门为农村或发展中地区的用户进行优化，你的时间可能更应该花在优化其他方面。

🌐 Generally, the round trip time to the server (100-200ms) will dwarf the time required to download an additional 10kb. Only on slow 3G connections (sub-1Mbps) does the download time for an additional 10kb become more significant. If you aren't optimizing specifically for users in rural or developing areas, your time is likely better spent optimizing something else.

ZodMiniType

所有 Zod Mini 模式都继承自 z.ZodMiniType 基类，而 z.ZodMiniType 又继承自 zod/v4/core 的 z.core.$ZodType。虽然这个类实现的方法远少于 zod 中的 ZodType，但一些特别有用的方法仍然存在。

🌐 All Zod Mini schemas extend the z.ZodMiniType base class, which in turn extends z.core.$ZodType from zod/v4/core. While this class implements far fewer methods than ZodType in zod, some particularly useful methods remain.

.parse

这是一个显而易见的例子。所有 Zod Mini 模式都实现与 zod 相同的解析方法。

🌐 This is an obvious one. All Zod Mini schemas implement the same parsing methods as zod.

import * as z from "zod/mini"
 
const mySchema = z.string();
 
mySchema.parse('asdf')
await mySchema.parseAsync('asdf')
mySchema.safeParse('asdf')
await mySchema.safeParseAsync('asdf')

.check()

在常规 Zod 中，schema 子类中有专门的方法用于执行常见检查：

🌐 In regular Zod there are dedicated methods on schema subclasses for performing common checks:

import * as z from "zod";
 
z.string()
  .min(5)
  .max(10)
  .refine(val => val.includes("@"))
  .trim()

在 Zod Mini 中，这些方法没有被实现。相反，你可以使用 .check() 方法将这些检查传入模式中：

🌐 In Zod Mini such methods aren't implemented. Instead you pass these checks into schemas using the .check() method:

import * as z from "zod/mini"
 
z.string().check(
  z.minLength(5), 
  z.maxLength(10),
  z.refine(val => val.includes("@")),
  z.trim()
);

已实现以下检查。其中一些检查仅适用于某些类型的模式（例如字符串或数字）。所有 API 都是类型安全的；TypeScript 不会允许你向模式添加不支持的检查。

🌐 The following checks are implemented. Some of these checks only apply to schemas of certain types (e.g. strings or numbers). The APIs are all type-safe; TypeScript won't let you add an unsupported check to your schema.

z.lt(value);
z.lte(value); // alias: z.maximum()
z.gt(value);
z.gte(value); // alias: z.minimum()
z.positive();
z.negative();
z.nonpositive();
z.nonnegative();
z.multipleOf(value);
z.maxSize(value);
z.minSize(value);
z.size(value);
z.maxLength(value);
z.minLength(value);
z.length(value);
z.regex(regex);
z.lowercase();
z.uppercase();
z.includes(value);
z.startsWith(value);
z.endsWith(value);
z.property(key, schema);
z.mime(value);
 
// custom checks
z.refine()
z.check()   // replaces .superRefine()
 
// mutations (these do not change the inferred types)
z.overwrite(value => newValue);
z.normalize();
z.trim();
z.toLowerCase();
z.toUpperCase();
 
// metadata (registers schema in z.globalRegistry)
z.meta({ title: "...", description: "..." });
z.describe("...");

.register()

用于在注册表中注册模式。

🌐 For registering a schema in a registry.

const myReg = z.registry<{title: string}>();
 
z.string().register(myReg, { title: "My cool string schema" });

.brand()

用于标记一个模式。有关更多信息，请参阅Branded 类型文档。

🌐 For branding a schema. Refer to the Branded types docs for more information.

import * as z from "zod/mini"
 
const USD = z.string().brand("USD");

.clone(def)

使用提供的 def 返回当前模式的一个相同克隆。

🌐 Returns an identical clone of the current schema using the provided def.

const mySchema = z.string()
 
mySchema.clone(mySchema._zod.def);

无默认语言环境

🌐 No default locale

虽然常规的 Zod 会自动加载英语（en）语言环境，但 Zod Mini 不会。在错误消息不必要、本地化为非英语语言或以其他方式自定义的情况下，这可以减小打包包的大小。

🌐 While regular Zod automatically loads the English (en) locale, Zod Mini does not. This reduces the bundle size in scenarios where error messages are unnecessary, localized to a non-English language, or otherwise customized.

这意味着，默认情况下，所有问题的 message 属性将简单地显示 "Invalid input"。要加载英文语言环境：

🌐 This means, by default the message property of all issues will simply read "Invalid input". To load the English locale:

import * as z from "zod/mini"
 
z.config(z.locales.en());

有关本地化的更多信息，请参阅 Locales 文档。

🌐 Refer to the Locales docs for more on localization.