Zod 的魔法:為什麼它能「定義一次,享受兩次」?
深入探討 Zod 如何利用 _output 與 z.infer,結束 TypeScript 型別與執行期驗證的長期分裂。
前言
最近回歸職場後,我注意到一個叫做 zod 的工具。
它非常神奇。它不只能用來驗證資料,它的規則竟然還能反過來變成 TypeScript 的型別,解決了很多過去處理型別時的麻煩。
我使用了一陣子後,就對它背後的原理非常好奇:「它究竟是怎麼辦到的?」
在深入探究後,我終於有了初步的理解,所以決定寫下這篇文章,分享我是如何搞懂這一切的。
在 TypeScript 的世界裡,我們一直在追求「類型安全」。但在 API 開發中,我們長期以來都活在一種「分裂」的狀態:
- 編譯期 (Compile Time): 我們手動編寫
interface或type,讓 VS Code 知道我們的資料長什麼樣子。 - 執行期 (Runtime): 我們用
Joi或其他驗證庫,再寫一套驗證規則,去檢查從前端或.env傳來的「不被信任的」資料。
這意味著我們必須維護兩套幾乎一樣的邏輯。只要一邊改了,另一邊忘了改,Bug 就會出現。
Zod,一個「TypeScript-first」的驗證庫,徹底解決了這個問題。它最神奇的地方,就是:「一套規則,兩種享受」。
Zod 的雙重職責
當你寫下這段 Zod Schema:
import { z } from 'zod';
// 1. Zod Schema (唯一的「事實來源」)
const UserSchema = z.object({
username: z.string().min(3),
email: z.string().email(),
});UserSchema 這個常數,其實同時扮演著兩種角色:
角色一:執行期的「保全」 (Validator)
這是在程式執行時的角色。UserSchema 是一個真實存在的 JavaScript 物件,它有一個 .parse() 方法。你可以用它來「驗證」真實的資料。
// 執行期:用 .parse() 驗證
try {
const user = UserSchema.parse({ username: 'al' }); // 👈 這會拋出錯誤
} catch (err) {
console.error(err); // ZodError: "username" must be at least 3 chars
}角色二:編譯期的「藍圖」 (Type Definition)
這是在程式編譯時(也就是在 VS Code 裡)的角色。Zod 巧妙地利用了 TypeScript 的類型系統,讓 UserSchema 這個變數本身「攜帶」了它所代表的 TypeScript 類型資訊。
而我們需要一個「鑰匙」來解鎖這個資訊。
解鎖魔法:z.infer 是如何運作的?
z.infer 就是那把「鑰匙」。它是一個只存在於 TypeScript 類型世界的工具。
// 編譯期:用 z.infer 抓取類型
type User = z.infer<typeof UserSchema>;
// User 類型被自動推導為:
// {
// username: string;
// email: string;
// }這個「自動推導」的背後,有兩個關鍵的 TypeScript 技術:
1. _output:Zod 藏好的「類型標籤」
Zod 的作者非常聰明。他們在 Zod 函式庫的原始碼中,為每一個驗證器(z.string, z.number...)的類型定義,都加上了一個隱藏的屬性,叫做 _output。
z.string()的類型定義中,藏著_output: string。z.number()的類型定義中, 藏著_output: number。
而 z.object() 這個組合器,會自動「組合」你傳入的所有 _output 標籤,產生一個新的 _output 標籤。
所以,當你定義 UserSchema 時,TypeScript 會自動幫你組合出,UserSchema 這個變數的類型上,攜帶了一個標籤:
_output: { username: string, email: string }2. extends 和 infer:拆禮物的工具
z.infer<T> 的內部原理,就是如同的「拆禮物」工具:
// Zod 函式庫中的(簡化)定義:
type z.infer<T> =
T extends { _output: infer O } // 👈 提問 + 填空
? O // 👈 回傳答案
: never;這段程式碼的白話文就是:
- T extends … (提問):
- 「嘿 TypeScript,傳進來的 T (也就是 UserSchema 的類型),它是不是一個『帶有 _output 標籤』的禮物盒?」
- { _output: infer O } (填空):
- 「如果是!那請你幫我『推斷 (infer)』出 _output 標籤裡面的類型是什麼,並把這個類型放進 O 這個空格裡。」
- ? O : never (回傳):
- 「提問成功,O 現在等於 { username: string, email: string }。好,我就把 O 回傳出去。」

結論
Zod 的魔法並非憑空而來,它建立在對 TypeScript 類型系統的深刻理解之上。
它透過在「Schema 物件」上同時附加「執行期驗證邏輯」和「編譯期類型標籤 (_output)」 ,並提供 z.infer 這個「類型讀取器」,完美地實現了「單一事實來源 (Single Source of Truth)」。
你只需要維護 Zod Schema,就能同時確保你的「執行期驗證」和「編譯期類型」100% 同步。這就是 Zod 如此強大且優雅的真正原因。