Zod Mini

注意 — Zod Mini 的文檔通過選項卡式代碼塊與常規 Zod 文檔交錯。本頁旨在解釋為什麼存在 Zod Mini，何時使用它，以及與常規 Zod 的一些主要區別。

Zod Mini 變體是隨 Zod 4 的發佈引入的。要嘗試它：

npm install zod@^4.0.0

要導入它：

import * as z from "zod/mini";

Zod Mini 實現與 zod 完全相同的功能，但使用 函數式、可 tree-shake 的 API。如果您來自 zod，這意味著您通常會使用函數代替方法。

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

Tree-shaking

Tree-shaking 是現代打包器用於從最終包中刪除未使用代碼的技術。它也被稱為 死代碼消除。

在常規 Zod 中，架構提供了一系列便捷方法來執行一些常見操作（例如字串架構上的 .min()）。打包器通常無法從您的包中刪除（「treeshake」）未使用的方法實現，但它們能夠刪除未使用的頂級函數。因此，Zod Mini 的 API 使用更多函數而不是方法。

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

為了讓您對包大小的減小有個大致瞭解，請考慮這個簡單的腳本：

z.boolean().parse(true)

使用 Zod 和 Zod Mini 打包此腳本會產生以下包大小。Zod Mini 減少了 64%。

包	包大小 (gzip)
Zod Mini	`2.12kb`
Zod	`5.91kb`

使用涉及對象類型的稍微複雜的架構：

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

包	包大小 (gzip)
Zod Mini	`4.0kb`
Zod	`13.1kb`

這讓您對所涉及的包大小有所瞭解。仔細查看這些數字並運行您自己的基準測試，以確定使用 Zod Mini 是否值得。

何時（及何時不）使用 Zod Mini (When (not) to use Zod Mini)

一般來說，除非您對包大小有非常嚴格的限制，否則您應該使用常規 Zod。許以開發人員大大高估了包大小對應用程序性能的重要性。在實踐中，Zod 規模的包大小（通常為 5-10kb）僅在為農村或發展中地區具有慢速移動網絡連接的用戶群優化前端包時才是一個有意義的問題。

讓我們瀏覽一些注意事項：

開發者體驗 (DX)

Zod Mini 的 API 更冗長且不易發現。與 Zod Mini 中的頂級函數相比，Zod API 中的方法通過 Intellisense更容易發現和自動完成。無法使用鏈式 API 快速構建架構。（作為 Zod 的創建者：我花了很多時間將 Zod Mini API 設計得儘可能符合人體工程學，但我仍然強烈偏好標準 Zod API。）

後端開發 (Backend development)

如果您在後端使用 Zod，Zod 規模的包大小沒有意義。即使在像 Lambda 這樣的資源受限環境中也是如此。這篇文章對不同大小的包的冷啟動時間進行了基準測試。以下是結果的一部分：

包大小	Lambda 冷啟動時間
`1kb`	`171ms`
`17kb` (非 Mini Zod gzip 大小)	`171.6ms` (interpolated)
`128kb`	`176ms`
`256kb`	`182ms`
`512kb`	`279ms`
`1mb`	`557ms`

可忽略不計的 1kb 包的最小冷啟動時間為 171ms。下一個測試的包大小是 128kb，僅增加了 5ms。當 gzip 壓縮後，整個常規 Zod 的包大小約為 17kb，這對應於啟動時間增加 0.6ms。

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 中，架構子類上有專用方法用於執行常見檢查：

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

在 Zod Mini 中，未實現此類方法。相反，您使用 .check() 方法將這些檢查傳遞給架構：

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

實施了以下檢查。其中一些檢查僅適用於特定類型的架構（例如字串或數字）。這些 API 都是類型安全的；TypeScript 不會讓您將不支持的檢查添加到架構中。

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()`

用於在註冊表中註冊架構。

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

`.brand()`

用於 品牌化 架構。有關更多信息，請參閱品牌類型文檔。

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

`.clone(def)`

使用提供的 def 返回當前架構的相同克隆。

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

沒有默認語言環境 (No default locale)

雖然常規 Zod 會自動加載英語 (en) 語言環境，但 Zod Mini 不會。這在不需要錯誤消息、本地化為非英語語言或以其他方式自定義的情況下減少了包大小。

這意味著，默認情況下，所有問題的 message 屬性將簡單地讀取 "Invalid input"。要加載英語語言環境：

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

有關本地化的更多信息，請參閱語言環境文檔。

Tree-shaking

何時（及何時不）使用 Zod Mini (When (not) to use Zod Mini)

開發者體驗 (DX)

後端開發 (Backend development)

互聯網速度 (Internet speed)

`ZodMiniType`

`.parse`

`.check()`

`.register()`

`.brand()`

`.clone(def)`

沒有默認語言環境 (No default locale)

On this page