zod

Zod 最佳实践

适用于 TypeScript 应用的 Zod 4 全面模式校验指南。涵盖 8 个类别中的 46 条规则，并按影响程度排序，以指导自动重构和代码生成。

适用场景

在以下情况下，请参考这些指南：

• 编写新的 Zod 模式
• 在 parse() 和 safeParse() 之间进行选择
• 使用 z.infer 实现类型推断
• 处理校验错误以向用户提供反馈
• 组合复杂对象模式
• 使用细化和转换
• 优化包体积和校验性能
• 审查 Zod 代码的最佳实践

按优先级划分的规则类别

优先级	类别	影响	前缀
1	模式定义	严重	schema-
2	解析与校验	严重	parse-
3	类型推断	高	type-
4	错误处理	高	error-
5	对象模式	中高	object-
6	模式组合	中	compose-
7	细化与转换	中	refine-
8	性能与包体积	低至中	perf-

快速参考

1. 模式定义（严重）

• schema-use-primitives-correctly - 为每种类型使用正确的基本类型模式
• schema-use-unknown-not-any - 使用 z.unknown() 代替 z.any()，确保类型安全
• schema-avoid-optional-abuse - 避免过度使用可选字段
• schema-string-validations - 在定义模式时应用字符串校验
• schema-use-enums - 为固定字符串值使用枚举
• schema-coercion-for-form-data - 对表单和查询数据使用强制转换

2. 解析与校验（严重）

• parse-use-safeparse - 对用户输入使用 safeParse()
• parse-async-for-async-refinements - 对异步细化使用 parseAsync
• parse-handle-all-issues - 处理所有校验问题，而不只是第一个
• parse-validate-early - 在系统边界处进行校验
• parse-avoid-double-validation - 避免对同一数据重复校验
• parse-never-trust-json - 绝不要信任 JSON.parse 的输出
• parse-validate-for-boolean-checks - 对是／否检查使用 validate()（Zod 4.6+）

3. 类型推断（高）

• type-use-z-infer - 使用 z.infer，而非手动定义类型
• type-input-vs-output - 对转换区分 z.input 和 z.infer
• type-export-schemas-and-types - 同时导出模式和推断类型
• type-branded-types - 使用品牌类型确保领域安全
• type-enable-strict-mode - 启用 TypeScript 严格模式

4. 错误处理（高）

• error-custom-messages - 提供自定义错误消息
• error-use-flatten - 使用 Zod 4 错误格式化辅助函数
• error-path-for-nested - 使用 issue.path 定位嵌套错误
• error-i18n - 实现国际化错误消息
• error-avoid-throwing-in-refine - 在 refine 中返回 false，而不是抛出异常

5. 对象模式（中高）

• object-strict-vs-strip - 明确选择未知键策略
• object-partial-for-updates - 对更新模式使用 partial()
• object-pick-omit - 使用 pick() 和 omit() 创建模式变体
• object-extend-for-composition - 使用 extend() 添加字段
• object-optional-vs-nullable - 区分 optional() 和 nullable()
• object-discriminated-unions - 使用可辨识联合进行类型收窄

6. 模式组合（中）

• compose-shared-schemas - 将共享模式提取到可复用模块中
• compose-intersection - 使用 intersection() 组合类型
• compose-lazy-recursive - 对递归模式使用 z.lazy()
• compose-preprocess - 使用 preprocess() 规范化数据
• compose-pipe - 使用 pipe() 进行多阶段校验

7. 优化与转换（中）

• refine-vs-superrefine - 正确选择 refine() 或 superRefine()
• refine-transform-coerce - 区分 transform()、refine() 和 coerce()
• refine-use-codec - 使用 z.codec() 进行双向转换（4.1+）
• refine-add-path - 为细化错误添加 path
• refine-defaults - 为带默认值的可选字段使用 default()
• refine-catch - 使用 catch() 实现容错解析

8. 性能与包体积（低-中）

• perf-cache-schemas - 缓存 schema 实例
• perf-zod-mini - 对包体积敏感的应用使用 Zod Mini
• perf-avoid-dynamic-creation - 避免在热点路径中动态创建 schema
• perf-lazy-loading - 延迟加载大型 schema
• perf-arrays - 优化大型数组的验证
• perf-compile-schemas - 使用 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

对于上面与任务匹配的每条规则，以及每个 scan 命中项，请阅读 references/<rule-id>.md，了解其重要性，以及错误与正确的代码示例。

相关技能

• 如需了解 React Hook Form 集成，请参阅 react-hook-form 技能

资料来源

• Zod 官方文档
• Zod v4 发布说明
• Zod GitHub 仓库
• Zod Mini
• Total TypeScript Zod 教程