定制错误

在 Zod 中，验证错误以 z.core.$ZodError 类的实例形式呈现。

zod 包中的 ZodError 类是一个子类，实现了一些额外的便利方法。

$ZodError 的实例包含 .issues 数组。每个 issue 包含一个人类可读的 message 和关于该问题的其他结构化元数据。

import * as z from "zod";
 
const result = z.string().safeParse(12); // { success: false, error: ZodError }
result.error.issues;
// [
//   {
//     expected: 'string',
//     code: 'invalid_type',
//     path: [],
//     message: '无效输入：预期字符串，收到数字'
//   }
// ]

每个 issue 都包含一个带有人类可读错误信息的 message 属性。错误信息可以通过多种方式自定义。

`error` 参数

几乎所有 Zod API 都接受一个可选的错误消息。

z.string("不是字符串！");

这个自定义错误会作为任何来自该模式的验证问题的 message 属性显示。

z.string("不是字符串！").parse(12);
// ❌ 抛出 ZodError {
//   issues: [
//     {
//       expected: 'string',
//       code: 'invalid_type',
//       path: [],
//       message: '不是字符串！'   <-- 👀 自定义错误信息
//     }
//   ]
// }

所有 z 函数和模式方法均接受自定义错误。

z.string("错误！");
z.string().min(5, "太短了！");
z.uuid("错误的 UUID！");
z.iso.date("无效日期！");
z.array(z.string(), "不是数组！");
z.array(z.string()).min(5, "元素太少！");
z.set(z.string(), "无效集合！");

如果愿意，也可以传入一个包含 error 参数的对象。

z.string({ error: "错误！" });
z.string().min(5, { error: "太短了！" });
z.uuid({ error: "错误的 UUID！" });
z.iso.date({ error: "无效日期！" });
z.array(z.string(), { error: "错误的数组！" });
z.array(z.string()).min(5, { error: "元素太少！" });
z.set(z.string(), { error: "无效集合！" });

error 参数也可以接受一个函数。错误定制函数在 Zod 中称为 错误映射（error map）。如果发生验证错误，错误映射会在解析时运行。

z.string({ error: () => `[${Date.now()}]: 验证失败。` });

错误映射会接收一个上下文对象，你可以根据验证问题来自定义错误信息。

z.string({
  error: (iss) => iss.input === undefined ? "该字段为必填项。" : "无效输入。"
});

对于高级场景，iss 对象提供了更多信息供你定制错误。

z.string({
  error: (iss) => {
    iss.code; // 问题代码
    iss.input; // 输入数据
    iss.inst; // 产生该问题的模式/检查
    iss.path; // 错误路径
  },
});

根据你使用的 API，可能会有其他可用属性。可以使用 TypeScript 的自动补全探索这些属性。

z.string().min(5, {
  error: (iss) => {
    // ...同上
    iss.minimum; // 最小值
    iss.inclusive; // 是否包含最小值
    return `密码必须有至少 ${iss.minimum} 个字符`;
  },
});

返回 undefined 以避免自定义错误消息，并回退到默认消息。（更具体地说，Zod 将控制权交给优先级链中的下一个错误映射。）这对于选择性地自定义某些错误消息而不自定义其他消息非常有用。

z.int64({
  error: (issue) => {
    // 覆盖 too_big 错误消息
    if (issue.code === "too_big") {
      return { message: `值必须小于 <${issue.maximum}` };
    }
 
    // 使用默认错误
    return undefined;
  },
});

针对单次解析的错误定制

要针对每次解析定制错误，可以向解析方法 parse 传入错误映射：

const schema = z.string();
 
schema.parse(12, {
  error: iss => "单次解析的自定义错误"
});

这比模式级别的自定义消息优先级低。

const schema = z.string({ error: "最高优先级" });
const result = schema.safeParse(12, {
  error: (iss) => "较低优先级",
});
 
result.error.issues;
// [{ message: "最高优先级", ... }]

iss 对象是所有可能的 issue 类型的区分联合类型。使用 code 属性区分它们。

详见所有 Zod issue 代码的拆解，参考 zod/v4/core 文档。

const result = schema.safeParse(12, {
  error: (iss) => {
    if (iss.code === "invalid_type") {
      return `无效类型，期望 ${iss.expected}`;
    }
    if (iss.code === "too_small") {
      return `最小值为 ${iss.minimum}`;
    }
    // ...
  }
});

在 issue 中包含输入值

默认情况下，Zod 不会在 issues 中包含输入数据。这是为了防止无意中记录可能敏感的输入数据。要在每个 issue 中包含输入数据，请使用 reportInput 标志：

z.string().parse(12, {
  reportInput: true
})
 
// ZodError: [
//   {
//     "expected": "string",
//     "code": "invalid_type",
//     "input": 12, // 👀
//     "path": [],
//     "message": "无效输入：预期字符串，收到数字"
//   }
// ]

全局错误定制

要指定全局错误映射，使用 z.config() 设置 Zod 的 customError 配置选项：

z.config({
  customError: (iss) => {
    return "全局修改后的错误";
  },
});

全局错误消息的优先级低于模式级别或单次解析的错误消息。

iss 对象是所有可能的 issue 类型的区分联合类型。使用 code 属性区分它们。

详见所有 Zod issue 代码的拆解，参考 zod/v4/core 文档。

z.config({
  customError: (iss) => {
    if (iss.code === "invalid_type") {
      return `无效类型，期望 ${iss.expected}`;
    }
    if (iss.code === "too_small") {
      return `最小值为 ${iss.minimum}`;
    }
    // ...
  },
});

国际化

为支持错误信息的国际化，Zod 提供了多个内置语言包（locales）。它们从 zod/v4/core 包导出。

注意 — 常规的 zod 库会自动加载 en 语言环境。Zod Mini 默认不会加载任何语言环境，所有错误信息都默认为“输入无效”。

import * as z from "zod";
import { en } from "zod/locales"
 
z.config(en());

若想懒加载语言包，可以考虑动态导入：

import * as z from "zod";
 
async function loadLocale(locale: string) {
  const { default: locale } = await import(`zod/v4/locales/${locale}.js`);
  z.config(locale());
};
 
await loadLocale("fr");

为了方便，所有语言包作为 z.locales 从 "zod" 导出。在某些打包器中，这可能无法进行摇树优化。

import * as z from "zod";
 
z.config(z.locales.en());

语言包列表

可用语言包如下：

ar — 阿拉伯语
az — 阿塞拜疆语
be — 白俄罗斯语
bg — 保加利亚语
ca — 加泰罗尼亚语
cs — 捷克语
da — 丹麦语
de — 德语
en — 英语
eo — 世界语
es — 西班牙语
fa — 波斯语
fi — 芬兰语
fr — 法语
frCA — 加拿大法语
he — 希伯来语
hu — 匈牙利语
hy — 亚美尼亚语
id — 印度尼西亚语
is — 冰岛语
it — 意大利语
ja — 日语
ka — 格鲁吉亚语
km — 高棉语
ko — 韩语
lt — 立陶宛语
mk — 马其顿语
ms — 马来语
nl — 荷兰语
no — 挪威语
ota — 土耳其文
ps — 普什图语
pl — 波兰语
pt — 葡萄牙语
ro — 罗马尼亚语
ru — 俄语
sl — 斯洛文尼亚语
sv — 瑞典语
ta — 泰米尔语
th — 泰语
tr — 土耳其语
uk — 乌克兰语
ur — 乌尔都语
uz — 乌兹别克语
vi — 越南语
zhCN — 简体中文
zhTW — 繁体中文
yo — 约鲁巴语

错误优先级

下面是确定错误优先级的快速参考：如果定义了多个错误定制，哪个优先？按从高到底优先级排序：

模式级错误 — 任何“硬编码”到模式定义中的错误消息。

z.string("不是字符串！");

单次解析错误 — 传入 .parse() 方法的自定义错误映射。

z.string().parse(12, {
  error: (iss) => "我的自定义错误"
});

全局错误映射 — 传给 z.config() 的自定义错误映射。

z.config({
  customError: (iss) => "我的自定义错误"
});

语言包错误映射 — 传给 z.config() 的语言包自定义错误映射。

z.config(z.locales.en());

error 参数