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 中，schema 提供了一系列便捷的方法来执行一些常见操作（例如，针对字符串 schema 的 .min()）。打包器通常无法从你的打包文件中移除（"treeshake"）未使用的方法实现，但它们可以移除未使用的顶层函数。因此，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

通常，除非对 bundle 大小有非常严格的限制，否则你应该使用常规 Zod。许多开发者大大高估了包大小对应用性能的重要性。实际上，只有在针对农村或发展中地区移动网络连接速度较慢的用户群优化前端 bundle 时，Zod 规模（通常为 5-10kb）的 bundle 大小才是有意义的考虑因素。

¥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。使用 gzip 压缩后，整个常规 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 Schema 都扩展了 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 Schema 都实现了与 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();

.register()

要在 registry 中注册模式。

¥For registering a schema in a registry.

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

.brand()

用于为 Schema 打上品牌烙印。有关核心子库内容的更多信息，请参阅 品牌类型 文档。

¥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());

有关更多信息，请参阅 语言环境 文档。

¥Refer to the Locales docs for more on localization.