如何在 Zod 与 Validator.js 结合验证中允许空字符串

本文介绍如何在使用 Zod 搭配 Validator.js 进行表单验证时，正确支持可选字段的空字符串（""）输入，避免 .refine 校验因 isAlpha("") 返回 false 而意外拒绝合法空值。

本文介绍如何在使用 Zod 搭配 Validator.js 进行表单验证时，正确支持可选字段的空字符串（`""`）输入，避免 `.refine` 校验因 `isAlpha("")` 返回 `false` 而意外拒绝合法空值。

在搭建类型安全的表单校验逻辑时，Zod 的优势在于运行时类型校验足够扎实，Validator.js 则更适合处理语义化规则，比如 isAlpha、isEmail 这类判断。可一旦把两者放到一起用，很多人都会踩到同一个坑：Validator.js 里大多数字符串校验方法（例如 validator.isAlpha）默认都不接受空字符串——哪怕这个字段在业务设定里本来就是可选的。

例如，你定义了一个仅允许英文字母、最多 maxChar 个字符、且自动转大写的字符串 schema：

const alpha = (maxChar: number = 1) =>
z
.string()
.toUpperCase()
.max(maxChar)
.refine((value) => validator.isAlpha(value.replaceAll(" ", ""), "en-US", { ignore: "" }));

这段代码看似合理，但存在两个关键问题：

1. value.replaceAll(" ", "") 在 value === "" 时仍返回 ""，而 validator.isAlpha("") 恒为 false；
2. .refine 是严格断言——只要回调返回 false，整个校验即失败，不会因字段“可选”而豁免（Zod 中“可选”需通过 .optional() 显式声明，而非依赖校验逻辑容忍空值）。

✅ 正确做法是显式将空字符串纳入合法范围：

const alpha = (maxChar: number = 1) =>
z
.string() // 注意：此处仍为必填 string；若字段真正可选，请外层套 .optional()
.toUpperCase()
.max(maxChar)
.refine(
(value) => validator.isAlpha(value) || value.length === 0,
{
message: "必须为空字符串或仅包含英文字母",
}
);

⚠️ 重要注意事项：

• 若该字段在业务中本就允许缺失（即 undefined 或未提交），请务必使用 .optional() 而非仅依赖空字符串逻辑：

  z.object({
  name: alpha(50).optional(), // ✅ 允许 undefined、null、"" 或有效字母串
  });

• validator.isAlpha("", "en-US") 始终为 false，这是 Validator.js 的设计行为，不可通过配置参数绕过（{ ignore: "" } 对空字符串无效）；
• 避免在 .refine 中重复处理空格等预处理逻辑（如 replaceAll），除非业务明确要求忽略空格后再校验——此时也需同步判断 value.trim() === "" 是否应被接受。

总结一下，关键点就在于：在 .refine 的回调里，明确补上一条 || value.length === 0 分支，同时再结合字段本身的语义，判断是否需要配合 .optional() 一起使用。这样处理，既不会丢掉 Validator.js 原有的校验能力，也更贴合前端表单里“可选文本字段”在真实交互中的表现。