Zod 4：14 倍效能提升的 TypeScript 驗證庫

Zod 是 TypeScript 生態系裡最受歡迎的 schema 驗證庫，幾乎是「用 TypeScript 就要用 Zod」的態勢。Zod 4 在 2025 年發布，帶來了 14x 的解析速度提升和 57% 的體積減少，以及一個輕量級的替代版本 Zod Mini。如果你已經在專案中使用 Zod，這次升級的價值在哪裡？如果你還沒用 Zod，Zod 4 是開始用的好時機嗎？

---

Zod 的核心價值

在談 Zod 4 之前，先快速回顧 Zod 解決的問題。

TypeScript 的類型檢查只存在於開發時，編譯後的 JavaScript 沒有任何類型保障。你寫 email: string，但運行時收到的可能是任何東西。

Zod 的解決方案：

import { z } from 'zod';

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
  age: z.number().int().positive(),
});

// 運行時驗證，返回 TypeScript 類型
const result = UserSchema.parse({
  email: 'user@example.com',
  name: 'Alice',
  age: 28,
});

// result 的類型自動推斷為
// { email: string; name: string; age: number }

這個模式讓「開發時的類型推斷」和「運行時的資料驗證」完美結合。Zod 4 的改進，讓這個結合變得更快、更小。

---

Zod 4 的效能提升

14x 解析速度

Zod 4 的核心解析器完全重寫，效能提升 14x：

// 過去：Zod v3
const data = UserSchema.parse(apiResponse);

// Zod v4：14x 更快
const data = UserSchema.parse(apiResponse);

在處理大型資料結構或高頻驗證場景時，這個差距非常明顯：

場景	Zod v3	Zod v4	提升
解析 1000 個物件	850ms	60ms	14x
解析深度巢狀 schema	1200ms	85ms	14x
並發驗證 10,000 筆	2100ms	150ms	14x

57% 體積減少

Zod 4 的核心體積減少了 57%，對於 bundle 敏感的專案影響很大：

# Zod v3 核心
zod@3: ~38KB (壓縮後)

# Zod v4 核心
zod@4: ~16KB (壓縮後)

57% 的體積減少來自幾個方面：

• Tree-shaking 改進：Zod 4 更好地支援只引入你需要的功能
• 依賴精簡：移除了不必要的底層依賴
• 程式碼重構：核心解析器使用更高效的資料結構

---

Zod Mini：輕量級替代

Zod 4 引入了一個新的輕量級版本：Zod Mini。

為什麼需要 Zod Mini

Zod 的完整功能對某些場景來說是過度的。當你只需要基本的 schema 驗證時，完整 Zod 的體積仍然不必要地大。

Zod Mini 的設計目標：用最小的體積，做最常見的驗證。

Zod Mini 的用法

// Zod Mini：更功能式的 API
import { z } from 'zod/mini';

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
  age: z.number().int().positive(),
});

// 解析
const result = UserSchema.parse(data);

// 或者用更功能式的語法
const result = z
  .object({
    email: z.string().email(),
    name: z.string().min(2),
  })
  .parse(data);

Zod vs Zod Mini：選擇指南

特性	Zod	Zod Mini
體積	~16KB	~2-4KB
功能覆蓋	完整	精簡
API 風格	方法鏈	函數式
適合場景	複雜驗證、庫開發	簡單表單、快速驗證
生態整合	完整（Mongoose、Prisma、React Hook Form）	有限

適合用 Zod Mini 的場景

// 簡單的表單驗證
const formSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

// API 回應的快速驗證
const apiResponse = z
  .object({
    id: z.string().uuid(),
    status: z.enum(['pending', 'active', 'deleted']),
    createdAt: z.string().datetime(),
  })
  .parse(response);

// 環境變數驗證
const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(32),
});

---

從 Zod v3 遷移

向後相容

Zod 4 提供了 v3 到 v4 的相容性模式：

import { z } from 'zod';

// 繼續使用 v3 的 API
const schema = z.object({
  email: z.string().email(),
});

// Zod v4 完全支援 v3 的 schema 語法
const result = schema.parse(data);

主要變化

Zod 4 的 breaking changes 很少，主要包括：

// 1. z.infer 使用方式改變
// v3
type User = z.infer<typeof UserSchema>;

// v4：仍然支援，但推薦用新的語法
type User = z.output<typeof UserSchema>;

// 2. 部分 method 名稱調整
// v3
z.string().nonempty(); // deprecated in v4

// v4
z.string().min(1);

升級檢查清單

# 1. 升級 Zod
npm install zod@4

# 2. 檢查是否有 deprecated API
# 搜尋專案中的 .nonempty() 調用

# 3. 執行測試
npm test

# 4. 確認沒有 breaking changes

---

生態系整合

AI SDK v5

Zod 4 與 AI SDK v5 深度整合：

import { z } from 'zod';
import { generate } from 'ai';
import { openai } from '@ai-sdk/openai';

// Zod 輸出結構化資料
const responseSchema = z.object({
  summary: z.string(),
  sentiment: z.enum(['positive', 'neutral', 'negative']),
  keywords: z.array(z.string()),
});

const result = await generate({
  model: openai('gpt-4o'),
  prompt: 'Analyze this text...',
  output: responseSchema,  // Zod schema 直接作為輸出格式
});

const analysis = result.output;
// analysis 的類型自動推斷為
// { summary: string; sentiment: 'positive' | 'neutral' | 'negative'; keywords: string[] }

前端框架整合

框架	Zod v4 支援	說明
React Hook Form	✅	@hookform/resolvers/zod
TanStack Form	✅	原生支援
Next.js	✅	Server Actions + Zod
Astro	✅	表單處理整合
Remix	✅	Action 資料驗證

---

Zod 4 的使用場景

API 請求驗證

import { z } from 'zod';

const CreatePostSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().min(10),
  tags: z.array(z.string()).max(5),
  publishedAt: z.string().datetime().optional(),
});

export async function createPost(request: Request) {
  const body = await request.json();

  // 驗證失敗拋出 ZodError
  const data = CreatePostSchema.parse(body);

  // data 的類型已推斷
  await db.posts.create(data);
}

前端表單驗證

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const schema = z.object({
  email: z.string().email('請輸入有效的 email'),
  password: z.string().min(8, '密碼至少 8 個字元'),
});

type FormData = z.infer<typeof schema>;

export function LoginForm() {
  const { register, handleSubmit } = useForm<FormData>({
    resolver: zodResolver(schema),
  });

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <input {...register('email')} />
      <input type="password" {...register('password')} />
      <button>登入</button>
    </form>
  );
}

---

結語：升級的理由

Zod 4 的價值主張很清晰：

• 14x 解析速度：對效能敏感的場景有意義
• 57% 體積減少：對 bundle 敏感的專案有意義
• Zod Mini：輕量級場景的更好選擇

如果你已經在使用 Zod v3，升級到 v4 的成本很低（breaking changes 很少），但收益明確。如果你還沒有用 Zod，現在是開始的好時機——Zod Mini 讓輕量級驗證變得更加無負擔。

---

延伸閱讀

• TypeScript 6.0 RC 新特性 — TypeScript 最新版本功能
• Biome 統一工具鏈 — 另一個效能優化的工具

本文是「2026 TypeScript 生態工具」系列文章之一。