Yup 类型校验错误消息自定义：typeError() 用法详解

• 文档
• 教程
• 知识库

导读

在基于 Yup 构建表单校验时，类型不匹配的默认报错往往冗长且面向开发者而非用户。本篇以 til 仓库中 Custom Type Checking Error Messages With Yup 为核心，讲解yup.number()等类型 schema 在验证失败时产生的默认消息结构，以及如何通过.typeError()将其替换为简洁、可直接展示给终端用户的文案；同时结合仓库内相关 TIL，串联起异步校验、跨字段校验与 Formik 集成等完整实战链路。

起点：一个强制类型为数字的 Yup schema

在 Yup Schemas Are Validated Asynchronously 中展示了如何用一条极简的 schema 强制某个值是数字：

const numSchema = yup.number();

Yup 的校验是异步的：校验通过时进入.then，失败时进入.catch，且失败原因对象上带有errors数组，其中包含所有校验错误消息：

const validator = (val) => { numSchema.validate(val) .then(result => { console.log(result); // 返回的正是 `val` 本身 return true; }) .catch(error => { console.log(error.errors); // 校验错误消息数组 return false; }); }; validator(5) // => true validator('what') // => false

默认类型错误消息：信息完整但不宜直接展示

用numSchema校验一个并非数字的值，例如字符串'hey'，Yup 会给出一条颇为冗长的默认消息：

this must be anumbertype, but the final value was:NaN(cast from the value"hey").

这条消息本身信息量很足，从结构上可以拆出两层含义：

• 前半段 "this must be anumbertype" 说明校验方期望的类型是 number；
• 括号中的 "(cast from the value"hey")" 暴露了 Yup 的底层行为——它先尝试把输入值'hey'强制转换（cast）为数字，得到NaN，随后类型检查失败。

问题在于，这种带内部实现细节的文案并不适合直接展示给表单用户：它暴露了 "cast"、"NaN" 等实现概念，普通用户既读不懂也没有必要看到。在面向用户的表单场景（注册、设置、下单等）中，我们通常希望错误消息是 "请输入数字" 这类人话。

用 typeError() 定制类型检查失败消息

Yup 提供了typeError()函数来重定义类型检查阶段的错误消息。在原 schema 上链式调用即可：

const numSchema = yup.number().typeError("Invalid number");

经过这样的改写，当校验'hey'这类非数字输入时，默认的冗长消息会被替换为简洁的Invalid number，而校验逻辑本身不受影响——5 依然通过，'hey'依然失败，只是失败消息变得可控了。

从仓库中其他 Yup 相关 TIL 可以看到，Yup 各校验器普遍遵循"最后一个参数即自定义消息"的约定：

• .required('Password is required')（见 Check The Password Confirmation With Yup）；
• .oneOf([Yup.ref('password'), null], 'Passwords must match')——oneOf的第二个参数就是校验失败时的自定义消息。

typeError()与这些"约束类"校验器的重要区别在于触发时机：typeError针对的是类型不匹配（值根本无法按 schema 类型转换），而required、oneOf、min、max等针对的是类型正确但约束不满足的值。因此自定义消息时应区分两类文案，例如：

const ageSchema = yup .number() .typeError('请输入年龄') .required('年龄不能为空') .min(0, '年龄不能为负数');

这样当用户输入 "abc" 时看到的是类型错误提示，输入空值时看到的是必填提示，输入 -5 时看到的是最小值提示，三类失败各归其位。

在表单校验场景中的完整落地

类型错误消息的自定义最有价值的场景是面向用户的表单。仓库中 Formik 的 validationSchema 用法 展示了 Yup schema 如何作为 Formik 的validationSchema直接驱动表单校验，而passwordConfirmation的例子（Check The Password Confirmation With Yup）则展示了跨字段引用Yup.ref('password')的写法。将二者与typeError()组合，可以得到一个贴近真实注册表单的 schema：

import * as Yup from 'yup'; const signupSchema = Yup.object({ age: Yup.number() .typeError('年龄必须是数字') // 类型不匹配时 .required('年龄不能为空') // 空值时 .min(0, '年龄不能为负数'), // 超出范围时 password: Yup.string().required('请输入密码'), passwordConfirmation: Yup.string() .oneOf([Yup.ref('password'), null], '两次输入的密码不一致') });

其中typeError保证了在年龄输入框里出现非数字内容时，用户看到的是清晰可理解的中文提示，而不是默认的 "this must be anumbertype, but the final value was:NaN..."。

小结

• Yup 的yup.number()等类型 schema 在遇到类型不匹配的值时，默认会生成包含 "cast"、"NaN" 等内部细节的冗长消息；
• 通过链式调用.typeError("自定义消息")可以将其替换为简洁、面向用户的文案，且不影响原有校验行为；
• 在 Yup Schemas Are Validated Asynchronously、Check The Password Confirmation With Yup 与 Formik 的 validationSchema 等仓库 TIL 的配合下，可以把类型检查、必填、范围与跨字段一致性等消息统一打磨成完整的表单体验。

• 文档
• 教程
• 知识库