zod

Zod

在涉及 Zod 验证、架构设计、类型推断、错误处理、JSON Schema、AOT 编译、Zod Mini、Zod Core 或从 Zod 3 迁移到 Zod 4 时，使用此技能。

快照：[email protected] / @zod/[email protected]（已于 2026-10-01 验证）。使用 Zod 4 的 latest 版本。不要使用 canary。若版本不同，请从 source-map.md 刷新文档。

工作流

1. 修改代码前，检查本地 Zod 使用情况：
   • zod、可选的 @zod/mini、验证适配器、表单库、API 层、代码生成器和 TypeScript 的包版本。
   • 导入：zod、zod/v4、zod/mini、@zod/mini、zod/v4/core、zod/compile 或 zod/v3。
   • 架构用途：不可信边界验证、API 契约、表单值、环境解析、持久化、JSON Schema/OpenAPI、热路径编译、库集成或迁移。
   • 类型流：z.input<>、z.output<> 和 z.infer<> 的使用位置，尤其是涉及转换、编解码器、强制转换、默认值和预处理器的情况。
2. 当用户询问最新/当前行为、无法确定已安装的版本，或工作涉及对迁移敏感的 API 时，刷新文档。从 source-map.md 开始。
3. 安装、导入、parse/validate/compile、类型推断、包变体和边界设计，请使用 setup-core.md。
4. 架构原语、字符串格式、对象、记录、数组、联合、递归架构、函数、品牌、z.toZod 和实例属性检查，请使用 schema-api.md。
5. 精化、.check()、转换、管道、预处理、编解码器、默认值、预填充值、捕获值和错误，请使用 effects-errors.md。
6. 元数据、注册表、JSON Schema 转换、Zod Mini、Zod Core、库作者支持，以及 Zod 4 / 4.5 / 4.6 迁移检查，请使用 metadata-jsonschema-migration.md。
7. 按照现有项目风格实现：
   • 遵循本地导入约定，除非版本边界要求使用不同的子路径。
   • 优先使用显式边界架构，避免使用宽泛的 z.any() 或未经检查的类型断言。
   • 在 API、表单、环境和存储边界处，确保解析和转换行为清晰可见。
   • 不要引入仅 canary 版本支持的行为。相较于 latest，npm 的 canary 已过时。

Zod 判断

• 将 schema 视为运行时契约，而不只是 TypeScript 类型工厂。
• 对可恢复的用户输入失败使用 safeParse，对无效数据属于异常情况时使用 parse。
• 如果只需要布尔类型守卫且不想产生 ZodError，请使用 .validate() / z.validate()。
• 只要任何 refinement、transform 或 codec 路径是异步的，就使用 parseAsync、safeParseAsync 或 validateAsync。
• 使用 coerce、preprocess、transform、pipe、codec、default、prefault 或 catch 时，请区分 z.input<> 和 z.output<>。运行时的 z.input(schema) / z.output(schema) 会分别映射 codec/pipe 的两侧。
• 编写新代码时，优先使用 Zod 4 顶层字符串格式 API（z.email()、z.uuid()、z.hash("sha256")、z.creditCard()、z.iban()、z.iso.datetime()），而不是已弃用的方法形式。
• 请记住，z.object() 默认会剔除未知键；请有意选择使用 z.strictObject()、z.looseObject() 或 .catchall()。__proto__ 始终会被剔除。
• 对于以枚举为键的 record，Zod 4 会检查其完整性。对于可选的枚举键映射，请使用 z.partialRecord()。
• 对象组合优先使用对象展开或 .extend()；扩展带有 refinement 的 schema 时使用 .safeExtend()。
• 双向序列化使用 codec，单向解析使用 transform。
• 使用 z.compile() 编译热点对象/数组/联合路径（或在应用中使用 import "zod/compile"）。编译最终 schema。不要在库中编译。
• 使用 z.instanceof(C).properties({ ... }) 原地验证类实例，而不要使用 z.object()。
• 对于库作者，支持 Zod 和 Zod Mini 时，请使用 zod/v4/core 和顶层 parse 辅助函数。新库只应将 zod@^4.0.0 声明为 peer 依赖。

验证

优先使用仓库中已有的检查。对于有实际意义的 Zod 工作，请包含相关子集：

• 对推断出的输入/输出类型、schema 组合、品牌、z.toZod<T>() 和库泛型约束进行类型检查。
• 针对有效输入、无效输入、未知键、默认值/预设值、转换、codec、异步路径和错误路径进行有针对性的测试。
• 对 API 处理程序、环境变量加载器、表单、服务端操作、CLI 和持久化适配器等边界解析器进行运行时冒烟测试。
• 对热点 schema 进行编译检查：有效输入仍应保持快速；无效输入仍应产生相同的问题；派生 schema（.extend()、.refine()）若需要快速路径，应重新编译。
• 当 schema 元数据或转换行为发生变化时，为 JSON Schema/OpenAPI 输出添加快照或契约测试。
• 对已弃用的 Zod 3 API、4.5/4.6 正确性修复（datetime 秒数、字符串码点、z.emoji()、JSON Schema 边界）、对象默认值、枚举 record、函数和已移除的内部 API 进行迁移检查。