Yup 入门：链式 Schema 数据校验

Yup 的链式 API 定义 Schema：yup.object({ email: yup.string().email().required() })，schema.validate(data) 异步校验。它是 React Hook Form/Formik 的经典搭档；新项目也建议评估 Zod（类型推导更现代）。

快速上手

npm install yup

import * as yup from 'yup';

const userSchema = yup.object({
  name: yup.string().min(2).required('姓名必填'),
  email: yup.string().email('邮箱格式错误').required(),
  age: yup.number().integer().min(18, '需年满 18 岁'),
  website: yup.string().url().optional(),
});

await userSchema.validate(data);              // 不符抛 ValidationError
await userSchema.validate(data, { abortEarly: false });  // 收集全部错误

校验链的丰富度

string（email/url/uuid/matches 正则）、number（min/max/positive）、date、array（of/min）、object（shape/noUnknown）——链式组合表达复杂规则：

password: yup.string()
  .min(8)
  .matches(/[A-Z]/, '需含大写字母')
  .matches(/[0-9]/, '需含数字')

自定义与依赖校验

confirmPassword: yup.string()
  .oneOf([yup.ref('password')], '两次密码不一致'),   // 引用其他字段

code: yup.string().test('check-code', '邀请码无效', async (value) => {
  return await api.verifyCode(value);   // 异步自定义校验
})

错误处理与表单集成

try {
  await schema.validate(data, { abortEarly: false });
} catch (err) {
  if (err instanceof yup.ValidationError) {
    const errors = Object.fromEntries(err.inner.map(e => [e.path, e.message]));
    // 映射到表单字段错误
  }
}

React Hook Form 的 yupResolver 直接把 Schema 接入表单——错误自动挂到字段。

TypeScript 集成

yup.InferType<typeof schema> 推导类型。注意：Yup 的类型推导精确度不及 Zod（optional 的处理等）——类型敏感项目评估 Zod。

常见问题（FAQ）

Q：Yup 和 Zod 怎么选？

存量 Formik/RHF + Yup 继续；新项目优先 Zod（推导精确、生态更现代）——见本系列《Joi 和 Zod 对比》的相关讨论。

Q：validate 是异步的为什么？

支持异步自定义校验（调 API）。同步场景用 validateSync（但含异步规则时会失败）。

Q：数据转换功能？

Yup 校验时可转换（trim/cast 自动）——cast() 只做转换不校验，清洗数据的场景有用。

---

参考文档

• Yup

本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。

延伸阅读

• Yarn 入门指南：可预期的依赖管理
• Yup 和 Zod 对比：校验库的新旧选择