Zod 表单验证中必填字段与最小长度的优先级处理

在使用 Zod 进行表单验证时，开发者经常会遇到一个常见问题：当字段为空时，验证错误消息的优先级问题。本文将以一个典型的表单验证场景为例，深入分析问题原因并提供两种有效的解决方案。

问题现象

在构建一个包含 firstName、lastName 和 emailAddress 的表单验证时，开发者期望当字段为空时显示"必填"错误，但实际上却显示了"太短"的错误提示。这是因为 Zod 的验证逻辑有其特定的处理方式。

根本原因

Zod 将空字符串 "" 视为有效的字符串类型，因此会跳过 required_error 的检查，直接进入后续的验证规则。在示例中，.min(2) 规则会首先捕获到空字符串（长度为0），从而显示"太短"的错误信息，而不是预期的"必填"提示。

解决方案一：链式最小长度验证

firstName: z
  .string()
  .min(1, "必填")  // 首先检查是否为空
  .min(2, "太短")  // 然后检查最小长度
  .trim()

这种方法通过设置两个连续的 .min() 验证：

1. 第一个 .min(1) 专门捕获空字符串情况
2. 第二个 .min(2) 处理实际的最小长度要求

解决方案二：使用 refine 和 pipe 组合

firstName: z
  .string()
  .refine(s => s !== "", "必填")  // 自定义空值检查
  .pipe(
    z.string()
      .min(2, "太短")  // 标准长度验证
      .trim()
  )

这种方案更加灵活：

1. 使用 .refine() 进行自定义的空值验证
2. 通过 .pipe() 将验证结果传递给后续的验证链
3. 保持了验证逻辑的清晰分离

最佳实践建议

1. 对于简单的必填字段验证，方案一的链式 .min() 更为简洁
2. 当需要更复杂的条件验证时，方案二的 .refine() 和 .pipe() 组合更具扩展性
3. 考虑在项目早期建立统一的验证模式，保持整个应用中的错误提示风格一致

通过理解 Zod 的验证机制并合理运用这些技巧，开发者可以构建出既符合业务需求又用户友好的表单验证系统。