用途
Zod 用于运行时类型校验，即在系统边界处解析不可信数据，例如 API 输入、表单数据、环境变量和外部服务返回的数据。对于仅需编译期类型的场景，普通 TypeScript 已足够。资料给出的工具选择对照：API 输入/输出校验用 Zod；表单校验（React、Vue）用 Zod 配合 react-hook-form、formik 等；环境变量解析用 Zod 配合 t3-env 或手动处理；仅编译期类型用普通 TypeScript；追求更小体积（约 1kb）可用 Valibot；追求最大类型推断可用 ArkType。
主要能力
本技能按优先级组织规则类别：解析与类型安全（CRITICAL）、模式设计（CRITICAL）、精炼与转换（HIGH）、错误处理（HIGH）、性能与组合（MEDIUM）、v4 迁移（MEDIUM）、高级模式（MEDIUM）、架构与边界（CRITICAL/HIGH）、可观测性（HIGH/MEDIUM）。
关键规则要点包括：使用 safeParse() 处理用户输入而非会抛错的 parse()；当模式含异步精炼时必须使用 parseAsync()/safeParseAsync()；使用 z.infer<typeof Schema> 获取输出类型，不要手动重复定义类型；z.object() 会剥离未知键，可用 strictObject 或 looseObject；带标签联合用 z.discriminatedUnion() 而非 z.union()；z.coerce.boolean() 会把 "false" 变为 true，应改用 z.stringbool()；递归模式用 getter 模式，v4 已移除 z.lazy()；不要在 .refine() 或 .transform() 内抛错，应使用 ctx.addIssue()；.refine() 用于校验、.transform() 用于转换、.pipe() 用于分阶段处理；跨字段校验在父对象上用 .superRefine() 并携带 path。
错误处理方面：使用 v4 的 error 参数，required_error/invalid_type_error 已移除；表单用 z.flattenError()，嵌套用 z.treeifyError()，formatError 已废弃；切勿在生产环境使用 reportInput: true，以免泄露敏感数据。
性能与组合：大型模式用 { ...Schema.shape } 展开优于链式 .extend()；模式定义一次后通过 .pick()、.omit()、.partial() 派生；对体积敏感的客户端应用可用 zod/v4/mini（1.88kb）。
v4 迁移：使用 z.email()、z.uuid()、z.url() 而非 z.string().email()；TypeScript 枚举使用统一的 z.enum()，z.nativeEnum() 已废弃；全面使用 error 参数，message、errorMap 已移除。
高级模式：用 .brand<"Name">() 实现名义类型（如区分 USD 与 EUR）；用 z.codec() 实现双向转换（解析加序列化）；用 .pipe() 实现分阶段解析（字符串转数字再校验范围）。
架构与边界：在系统边界（API 处理器、环境变量、表单、fetch）解析，将已定类型数据传入领域逻辑；模式与边界层就近放置，领域类型使用 z.infer；非破坏性演进仅做增量变更，新字段使用 .optional()。
可观测性：用 z.flattenError() 生成带请求关联 ID 的紧凑结构化日志；用 trackedSafeParse() 包装器在失败时按模式与字段递增计数器。
使用方式
阅读各规则文件以获取详细说明与代码示例，例如 rules/parse-use-safeParse.md、rules/schema-object-unknowns.md。每个规则文件包含：为什么重要的简要说明、带解释的错误代码示例、带解释的正确代码示例，以及额外上下文与决策表。
参考文档按优先级排列：references/schema-types.md（所有基础类型、字符串格式、数字、枚举、日期）；references/parsing-and-inference.md（parse、safeParse、z.infer、强制转换）；references/objects-and-composition.md（对象、数组、联合、pick/omit/partial、递归）；references/refinements-and-transforms.md（refine、superRefine、transform、pipe、默认值）；references/error-handling.md（ZodError、flattenError、treeifyError、错误定制）；references/advanced-features.md（Codecs、品牌类型、JSON Schema、注册表）；references/anti-patterns.md（常见错误与正反示例）；references/boundary-architecture.md（Zod 在 Express、tRPC、Next.js、React Hook Form、环境变量、外部 API 中的位置）；references/linter-and-ci.md（ESLint 规则、CI 模式快照、未使用模式检测、循环依赖）；references/testing.md（测试模式：测试中的 safeParse、边界值、错误断言、模拟数据、基于属性的测试）；references/testing-api.md（模式测试的 Jest 与 Vitest API 参考）；references/testing-anti-patterns.md（测试错误与正反示例）。完整指南见 AGENTS.md。
适用场景
适用于在 TypeScript 应用中需要在系统边界解析不可信数据的场景，包括 API 输入输出校验、表单校验、环境变量解析、外部服务数据校验等。资料中的模式类型速查表列出常用类型语法：z.string()、z.number()、z.int()、z.float()、z.boolean()、z.bigint()、z.date()、z.undefined()、z.null()、z.void()、z.any()、z.unknown()、z.never()、z.literal()、z.enum()、z.email()、z.url()、z.uuid()、z.stringbool()、z.iso.datetime()、z.file()、z.json()、z.array()、z.tuple()、z.object()、z.strictObject()、z.looseObject()、z.record()、z.map()、z.set()、z.union()、z.discriminatedUnion()、z.intersection()。
限制
资料未提供关于收费、价格、具体平台支持范围、性能基准或实际效果的信息，暂未提供。资料强调 Zod v4 在字符串格式、枚举、错误处理与递归类型上有破坏性变更，使用时不应回退到记忆中的 v3 模式，应以本技能的规则文件和项目实际源码为准。