Zod 中如何实现可选字段或最小长度约束

问题描述

在 TypeScript 开发中使用 Zod 进行表单验证时，常遇到这样的需求：某个字段既可以是可选的（允许为空），或者在提供值时必须满足最小长度要求。具体场景如下：

• 当用户不输入该字段时，应通过验证
• 当用户输入字段时，必须至少包含 4 个字符
• 应正确地将空字符串（""）处理为未定义（undefined）
• 需要符合 TypeScript 类型安全要求

原始尝试方案存在的问题：

export const SocialsSchema = z.object({
  myField: z.optional(z.string().min(4, "Please enter a valid value")), 
});
// 当 myField = "" 时验证失败

最佳解决方案

推荐方案：使用值转换与联合类型

通过 Zod 的 union() 和 transform() 方法，创建一个可复用的高阶函数：

import { z } from "zod";

function optionalWithMin(schema: z.ZodString) {
  return z
    .union([z.string().length(0), schema]) // 先检查空字符串再应用约束
    .optional()
    .transform(value => value === "" ? undefined : value);
}

export const SocialsSchema = z.object({
  myField: optionalWithMin(z.string().min(4, "值至少需要4个字符"))
});

方案特点：

• ✅ 正确将空字符串视为未定义
• ✅ 满足最小长度约束
• ✅ 清晰的错误提示
• ❌ 避免使用正则表达式
• ✅ 返回 TypeScript 类型：string | undefined

替代方案：使用 or() 与 optional()

如果不需要转换空字符串为 undefined：

export const SocialsSchema = z.object({
  myField: z
    .string()
    .min(4, "值至少需要4个字符")
    .optional()
    .or(z.literal('')) // 允许空字符串但不转换
});

适用场景：

• 需要显式保留空字符串值
• 不需要类型转换时

方法对比分析

可选+转换方案

function optionalWithMin(schema: z.ZodString) {
  return z
    .union([z.string().length(0), schema])
    .optional()
    .transform(v => v === "" ? undefined : v);
}

// 类型: string | undefined

or() + optional() 方案

z.string()
  .min(4)
  .optional()
  .or(z.literal(''));

// 类型: string | undefined | ""

不同用例下的验证结果：

输入值	可选+转换方案	or()+optional()方案
{}	✅ (undefined)	✅ (undefined)
{ myField: undefined }	✅	✅
{ myField: "" }	✅ (转 undefined)	✅
{ myField: "1234" }	✅	✅
{ myField: "abc" }	❌ 最小长度错误	❌ 最小长度错误
{ myField: 1234 }	❌ 类型错误	❌ 类型错误

错误处理机制

注意错误提示优先级

联合类型中验证器的顺序直接影响错误消息：

// ❌ 错误做法：可能返回不准确的错误信息
z.union([
  z.string().min(4), 
  z.string().length(0)
])

// ✅ 正确做法：优先处理空字符串
z.union([
  z.string().length(0), // 首先匹配空字符串
  z.string().min(4)     // 然后检查约束
])

错误顺序会导致输入 "abc" 时显示 "字符串必须为空" 而非最小长度错误

进阶使用场景

自定义默认值处理

function optionalField(schema: z.ZodTypeAny, defaultValue?: unknown) {
  return z
    .union([z.string().length(0), schema])
    .optional()
    .transform(value => {
      if (value === "") return defaultValue;
      return value;
    });
}

// 使用示例：空字符串转为默认值
const schema = z.object({
  username: optionalField(z.string().min(4), "guest")
});

条件验证

当字段之间存在依赖关系时的处理：

const UserSchema = z.object({
  subscribe: z.boolean(),
  email: z.string().email().optional()
}).refine(data => {
  if (data.subscribe) {
    return !!data.email; // 订阅时email必填
  }
  return true;
}, {
  message: "订阅用户必须提供邮箱",
  path: ["email"]
});

最佳实践总结

1. 空字符串处理原则：

   • 使用 transform() 将空字符串转为 undefined
   • 优先使用联合类型确保正确验证顺序

2. 模块化管理：

   // utils/zodHelpers.ts
   export function optionalString(schema: z.ZodString) {
     return z.union([z.string().length(0), schema])
       .optional()
       .transform(v => v === "" ? undefined : v);
   }
   
   // 在业务模型中引用
   import { optionalString } from "./utils/zodHelpers";

3. 复杂场景优化：

   z.discriminatedUnion("type", [
     z.object({
       type: z.literal("email"),
       address: z.string().email()
     }),
     z.object({
       type: z.literal("sms"),
       phone: z.string().length(11)
     })
   ]);

迁移技巧

从其他校验库迁移到 Zod 时：

1. 优先实现核心验证逻辑
2. 通过 z.preprocess() 处理特殊格式
3. 使用 .pipe() 链接复杂条件验证

以上方案在 Zod v3.21+ 中验证通过，完美解决「可选字段或最小长度」的验证需求，同时保持类型安全和清晰的错误提示。