Zod Core

此子包導出 Zod 和 Zod Mini 使用的核心類和實用程序。它不打算直接使用；相反，它被設計為由其他包擴展。它實現了：

import * as z from "zod/v4/core";
 
// the base class for all Zod schemas
z.$ZodType;
 
// subclasses of $ZodType that implement common parsers
z.$ZodString
z.$ZodObject
z.$ZodArray
// ...
 
// the base class for all Zod checks
z.$ZodCheck;
 
// subclasses of $ZodCheck that implement common checks
z.$ZodCheckMinLength
z.$ZodCheckMaxLength
 
// the base class for all Zod errors
z.$ZodError;
 
// issue formats (types only)
{} as z.$ZodIssue;
 
// utils
z.util.isValidJWT(...);

架構 (Schemas)

所有 Zod 架構的基類是 $ZodType。它接受兩個泛型參數：Output 和 Input。

export class $ZodType<Output = unknown, Input = unknown> {
  _zod: { /* internals */}
}

zod/v4/core 導出了許多實現代碼常見解析器的子類。所有第一方子類的聯合作為 z.$ZodTypes 導出。

export type $ZodTypes =
  | $ZodString
  | $ZodNumber
  | $ZodBigInt
  | $ZodBoolean
  | $ZodDate
  | $ZodSymbol
  | $ZodUndefined
  | $ZodNullable
  | $ZodNull
  | $ZodAny
  | $ZodUnknown
  | $ZodNever
  | $ZodVoid
  | $ZodArray
  | $ZodObject
  | $ZodUnion // $ZodDiscriminatedUnion extends this
  | $ZodIntersection
  | $ZodTuple
  | $ZodRecord
  | $ZodMap
  | $ZodSet
  | $ZodLiteral
  | $ZodEnum
  | $ZodPromise
  | $ZodLazy
  | $ZodOptional
  | $ZodDefault
  | $ZodTemplateLiteral
  | $ZodCustom
  | $ZodTransform
  | $ZodNonOptional
  | $ZodReadonly
  | $ZodNaN
  | $ZodPipe // $ZodCodec extends this
  | $ZodSuccess
  | $ZodCatch
  | $ZodFile;

內部結構 (Internals)

所有 zod/v4/core 子類僅包含一個屬性：_zod。此屬性是一個包含架構 內部結構 的對象。目標是使 zod/v4/core 儘可能具有可擴展性和無偏見。其他庫可以在這些類之上「構建自己的 Zod」，而不會讓 zod/v4/core 混亂接口。有關如何擴展這些類的示例，請參閱 zod 和 zod/mini 的實現。

_zod 內部屬性包含一些值得注意的屬性：

.def — 架構的定義：這是您傳遞給類的構造函數以創建實例的對象。它完全描述了架構，並且是 JSON 可序列化的。
- .def.type — 表示架構類型的字串，例如 "string"、"object"、"array" 等。
- .def.checks — 解析後由架構執行的檢查數組。
.input — 一個「存儲」架構 推斷輸入類型 的虛擬屬性。
.output — 一個「存儲」架構 推斷輸出類型 的虛擬屬性。
.run() — 架構的內部解析器實現。

如果您正在實現一個必須遍歷 Zod 架構的工具（例如代碼生成器），您可以將任何架構轉換為 $ZodTypes 並使用 def 屬性來區分這些類。

export function walk(_schema: z.$ZodType) {
  const schema = _schema as z.$ZodTypes;
  const def = schema._zod.def;
  switch (def.type) {
    case "string": {
      // ...
      break;
    }
    case "object": {
      // ...
      break;
    }
  }
}

有許多 $ZodString 的子類實現了各種 字串格式。這些作為 z.$ZodStringFormatTypes 導出。

export type $ZodStringFormatTypes =
  | $ZodGUID
  | $ZodUUID
  | $ZodEmail
  | $ZodURL
  | $ZodEmoji
  | $ZodNanoID
  | $ZodCUID
  | $ZodCUID2
  | $ZodULID
  | $ZodXID
  | $ZodKSUID
  | $ZodISODateTime
  | $ZodISODate
  | $ZodISOTime
  | $ZodISODuration
  | $ZodIPv4
  | $ZodIPv6
  | $ZodCIDRv4
  | $ZodCIDRv6
  | $ZodBase64
  | $ZodBase64URL
  | $ZodE164
  | $ZodJWT

解析 (Parsing)

由於 Zod Core 架構類沒有方法，因此有頂級函數用於解析數據。

import * as z from "zod/v4/core";
 
const schema = new z.$ZodString({ type: "string" });
z.parse(schema, "hello");
z.safeParse(schema, "hello");
await z.parseAsync(schema, "hello");
await z.safeParseAsync(schema, "hello");

檢查 (Checks)

每個 Zod 架構都包含一個檢查數組。這些執行解析後的細化（偶爾是突變），這些細化 不會影響 推斷類型。

const schema = z.string().check(z.email()).check(z.min(5));
// => $ZodString
 
schema._zod.def.checks;
// => [$ZodCheckEmail, $ZodCheckMinLength]

所有 Zod 檢查的基類是 $ZodCheck。它接受單個泛型參數 T。

export class $ZodCheck<in T = unknown> {
  _zod: { /* internals */}
}

_zod 內部屬性包含一些值得注意的屬性：

.def — 檢查的定義：這是您傳遞給類的構造函數以創建檢查的對象。它完全描述了檢查，並且是 JSON 可序列化的。
- .def.check — 表示檢查類型的字串，例如 "min_length"、"less_than"、"string_format" 等。
.check() — 包含檢查的驗證邏輯。

zod/v4/core 導出了許多執行常見細化的子類。所有第一方子類的聯合作為 z.$ZodChecks 導出。

export type $ZodChecks =
  | $ZodCheckLessThan
  | $ZodCheckGreaterThan
  | $ZodCheckMultipleOf
  | $ZodCheckNumberFormat
  | $ZodCheckBigIntFormat
  | $ZodCheckMaxSize
  | $ZodCheckMinSize
  | $ZodCheckSizeEquals
  | $ZodCheckMaxLength
  | $ZodCheckMinLength
  | $ZodCheckLengthEquals
  | $ZodCheckProperty
  | $ZodCheckMimeType
  | $ZodCheckOverwrite
  | $ZodCheckStringFormat

您可以使用 ._zod.def.check 屬性來區分這些類。

const check = {} as z.$ZodChecks;
const def = check._zod.def;
 
switch (def.check) {
  case "less_than":
  case "greater_than":
    // ...
    break;
}

與架構類型一樣，有許多 $ZodCheckStringFormat 的子類實現了各種 字串格式。

export type $ZodStringFormatChecks =
  | $ZodCheckRegex
  | $ZodCheckLowerCase
  | $ZodCheckUpperCase
  | $ZodCheckIncludes
  | $ZodCheckStartsWith
  | $ZodCheckEndsWith
  | $ZodGUID
  | $ZodUUID
  | $ZodEmail
  | $ZodURL
  | $ZodEmoji
  | $ZodNanoID
  | $ZodCUID
  | $ZodCUID2
  | $ZodULID
  | $ZodXID
  | $ZodKSUID
  | $ZodISODateTime
  | $ZodISODate
  | $ZodISOTime
  | $ZodISODuration
  | $ZodIPv4
  | $ZodIPv6
  | $ZodCIDRv4
  | $ZodCIDRv6
  | $ZodBase64
  | $ZodBase64URL
  | $ZodE164
  | $ZodJWT;

使用嵌套的 switch 來區分不同的字串格式檢查。

const check = {} as z.$ZodChecks;
const def = check._zod.def;
 
switch (def.check) {
  case "less_than":
  case "greater_than":
  // ...
  case "string_format":
    {
      const formatCheck = check as z.$ZodStringFormatChecks;
      const formatCheckDef = formatCheck._zod.def;
 
      switch (formatCheckDef.format) {
        case "email":
        case "url":
          // do stuff
      }
    }
    break;
}

您會注意到其中一些字串格式檢查與上面的字串格式類型重疊。這是因為這些類同時實現了 $ZodCheck 和 $ZodType 接口。也就是說，它們可以用作檢查或類型。在這些情況下，._zod.parse（架構解析器）和 ._zod.check（檢查驗證）都會在解析期間執行。實際上，實例被添加到它自己的 checks 數組的前面（儘管它實際上不存在於 ._zod.def.checks 中）。

// as a type
z.email().parse("[email protected]");
 
// as a check
z.string().check(z.email()).parse("[email protected]")

錯誤 (Errors)

Zod 中所有錯誤的基類是 $ZodError。

出於性能原因，$ZodError 不擴展內置的 Error 類！因此使用 instanceof Error 將返回 false。

zod 包實現了一個名為 ZodError 的 $ZodError 子類，並帶有一些額外的便捷方法。
zod/mini 子包直接使用 $ZodError

export class $ZodError<T = unknown> implements Error {
 public issues: $ZodIssue[];
}

問題 (Issues)

issues 屬性對應於 $ZodIssue 對象的數組。所有問題都擴展 z.$ZodIssueBase 接口。

export interface $ZodIssueBase {
  readonly code?: string;
  readonly input?: unknown;
  readonly path: PropertyKey[];
  readonly message: string;
}

Zod 定義了以下問題子類型：

export type $ZodIssue =
  | $ZodIssueInvalidType
  | $ZodIssueTooBig
  | $ZodIssueTooSmall
  | $ZodIssueInvalidStringFormat
  | $ZodIssueNotMultipleOf
  | $ZodIssueUnrecognizedKeys
  | $ZodIssueInvalidUnion
  | $ZodIssueInvalidKey
  | $ZodIssueInvalidElement
  | $ZodIssueInvalidValue
  | $ZodIssueCustom;

有關每種類型的詳細信息，請參閱實現。