zod

Zod 4 是一个用于 TypeScript 应用的 schema 校验与类型推断工具。本技能是一份面向 Zod 4 的综合 schema 校验指南，包含 8 个类别、共 46 条规则，按影响程度划分优先级，用于指导自动化重构与代码生成。

适用时机

在以下情况可参考这些指南：编写新的 Zod schema；在 parse() 与 safeParse() 之间做选择；使用 z.infer 实现类型推断；处理校验错误以向用户提供反馈；组合复杂的对象 schema；使用 refinement 与 transform；优化打包体积与校验性能；审查 Zod 代码是否符合最佳实践。

规则类别与优先级

Schema 定义（CRITICAL，前缀 schema-）：为每种类型使用正确的原始 schema；使用 z.unknown() 而非 z.any() 以保证类型安全；避免过度使用可选字段；在 schema 定义处应用字符串校验；对固定字符串值使用枚举；对表单和查询数据使用强制转换。
解析与校验（CRITICAL，前缀 parse-）：对用户输入使用 safeParse()；对异步 refinement 使用 parseAsync；处理所有校验问题而非仅第一个；在系统边界处进行校验；避免对同一数据重复校验；永远不要信任 JSON.parse 的输出；使用 validate() 进行是/否判断（Zod 4.6+）。
类型推断（HIGH，前缀 type-）：使用 z.infer 而非手写类型；对 transform 区分 z.input 与 z.infer；同时导出 schema 与推断出的类型；使用 branded types 保证领域安全；启用 TypeScript strict 模式。
错误处理（HIGH，前缀 error-）：提供自定义错误消息；使用 Zod 4 的错误格式化辅助工具；使用 issue.path 定位嵌套错误；实现国际化错误消息；在 refine 中返回 false 而非抛出异常。
对象 Schema（MEDIUM-HIGH，前缀 object-）：选择明确的未知键策略（strict 与 strip）；对更新 schema 使用 partial()；使用 pick() 与 omit() 生成 schema 变体；使用 extend() 添加字段；区分 optional() 与 nullable()；使用可辨识联合进行类型收窄。
Schema 组合（MEDIUM，前缀 compose-）：将共享 schema 抽取为可复用模块；使用 intersection() 组合类型；使用 z.lazy() 处理递归 schema；使用 preprocess() 做数据规范化；使用 pipe() 进行多阶段校验。
Refinement 与 Transform（MEDIUM，前缀 refine-）：正确选择 refine() 与 superRefine()；区分 transform()、refine() 与 coerce()；使用 z.codec() 进行双向转换（4.1+）；为 refinement 错误添加 path；对带默认值的可选字段使用 default()；使用 catch() 实现容错解析。
性能与打包（LOW-MEDIUM，前缀 perf-）：缓存 schema 实例；对打包体积敏感的应用使用 Zod Mini；避免在热路径中动态创建 schema；懒加载大型 schema；优化大型数组校验；使用 z.compile 编译热路径 schema（Zod 4.5+）。

使用方式

先在项目根目录运行：

npx -y @pymodel/react-frontend-skills detect # installed vs. targeted versions npx -y @pymodel/react-frontend-skills scan --skill zod # deprecated APIs → rule IDs

针对上述每条与任务匹配的规则以及每个扫描命中项，阅读 references/<rule-id>.md，了解其重要性以及错误与正确代码的对比。

技能介绍