如何为Zod元组添加自定义提示消息？

要替换Zod元组长度不足时的默认提示消息，不能直接通过tuple的第二个参数设置（该参数仅控制非数组类型输入的错误提示），可以用superRefine手动校验长度并抛出自定义错误，具体代码如下：

const tupleSchema = z.tuple([
    z.enum(['option1', 'option2']), // 需补充枚举可选值，避免语法错误
    z.number(),
    z.string(),
    z.array(z.any())
]).superRefine((value, context) => {
    // 校验数组长度是否符合元组要求
    if (value.length !== 4) {
        context.addIssue({
            code: z.ZodIssueCode.too_small,
            minimum: 4,
            type: 'array',
            message: '请输入包含4个元素的数组，顺序需为：枚举值、数字、字符串、数组'
        });
    }
});

// 测试示例
try {
    tupleSchema.parse(['option1', 100, 'hello', [1,2,3]]);
    console.log('校验通过');
} catch (error) {
    console.log(error.errors[0].message); // 长度不符时输出自定义提示
}

关键说明 #

• 原tuple配置的message仅作用于输入不是数组的场景（比如传入字符串、数字），无法覆盖长度校验的错误提示
• superRefine会在Zod内置校验后执行，能手动添加自定义校验逻辑和错误信息，完全替换默认的"Array must contain at least 4 element(s)"提示
• 如果需要批量修改所有元组的长度提示，可以使用Zod全局errorMap，但针对单个schema的场景用superRefine更灵活

内容的提问来源于stack exchange，提问作者StackKaan