Vue 3 + Vuelidate 自定义必传校验实战：从原理到避坑

1. 为什么表单校验值得单独拎出来聊

做前端表单校验这件事，说简单也简单，说麻烦是真麻烦。简单在于，一个required属性就能挡住大部分空值提交；麻烦在于，真实业务里的"必填"往往不是"非空"两个字能概括的。比如一个上传组件，用户选了文件但没点上传，字段值是个空数组，required判定为通过，可业务上这就是没填；再比如一个多选标签输入，用户输入了内容但没回车确认，值还是空的，界面上看着"填了"，提交时却报错，用户一脸懵。

我最近在一个后台管理系统里就踩了这类坑。项目用的是 Vue 3 + Vuelidate 这套组合，Vuelidate 本身是个很轻量的校验库，基于组合式 API 写起来很顺手，但它的内置校验器（required、minLength、email这些）只覆盖了最基础的场景。一旦遇到"自定义必传项"——也就是那些需要根据业务规则判断是否算"已填写"的字段——内置校验器就不够用了，必须自己写自定义校验函数。

这篇内容就是把我这段时间用 Vuelidate 做自定义必传校验的完整思路、代码实现、踩过的坑和排查技巧整理出来。适合正在用 Vue 3 + Vuelidate 做表单的开发者，也适合那些被"看起来填了其实没填"这类问题折磨过的朋友。我会从设计思路讲到具体实现，再到常见问题的排查，尽量把每个"为什么这么写"都讲清楚，让你看完能直接抄作业，也能理解背后的逻辑，遇到变体场景自己能改。

核心关键词会围绕Vuelidate 自定义校验、必传项校验、Vue 3 表单验证、自定义校验函数、表单校验避坑这几个方向展开，这些都是实际开发中高频出现的搜索需求。

2. Vuelidate 的校验机制与自定义校验的切入点

2.1 Vuelidate 的核心工作方式

要写好自定义校验，得先搞清楚 Vuelidate 是怎么运转的。它和那些"绑定在组件上自动校验"的库不太一样，Vuelidate 的核心思路是：你把校验规则定义成一个对象，这个对象的结构和你表单数据的结构一一对应，然后 Vuelidate 帮你追踪每个字段的校验状态。

用组合式 API 的写法大概是这样：

import { useVuelidate } from '@vuelidate/core' import { required, minLength } from '@vuelidate/validators' import { reactive } from 'vue' const formData = reactive({ username: '', tags: [] }) const rules = { username: { required, minLength: minLength(3) }, tags: { required } } const v$ = useVuelidate(rules, formData)

这里rules对象的 key 必须和formData的 key 对应，Vuelidate 会遍历这些规则，对每个字段执行校验函数。校验函数返回true表示通过，返回false表示失败。这是最基础的认知，但很多人卡在自定义校验上，恰恰是因为没意识到：自定义校验函数本质上就是一个接收"当前值"、返回布尔值（或 Promise）的普通函数，没什么神秘的。

2.2 内置校验器为什么不够用

Vuelidate 内置的required校验器，源码逻辑大致是判断值是否为null、undefined、空字符串，或者空数组。听起来挺全的，但实际业务里"必填"的定义千差万别：

• 文件上传场景：字段值是文件对象数组，用户选了文件但没触发上传，数组里可能有临时对象，required判定通过，但业务上文件还没真正上传成功，不算填了。
• 标签输入场景：用户输入了文字但没按回车确认，绑定值还是空数组，界面上看着有内容，实际值是空的。
• 级联选择场景：用户选了省但没选市，字段值是个不完整的对象，required只看对象非空，判定通过，但业务要求必须选到最末级。
• 富文本场景：编辑器里只有空标签<p><br></p>，字符串非空，required通过，但实际没有任何有效内容。

这些场景的共同点是："是否已填写"需要业务逻辑来判断，而不是简单的非空判断。这就是自定义校验函数要解决的问题。

2.3 自定义校验函数的两种写法

Vuelidate 支持两种自定义校验的写法，各有适用场景。

第一种是内联箭头函数，适合逻辑简单的场景：

const rules = { tags: { required: (value) => Array.isArray(value) && value.length > 0 } }

第二种是独立函数，适合逻辑复杂、需要复用或需要传参的场景：

const mustHaveAtLeastOne = (minCount = 1) => { return (value) => { if (!Array.isArray(value)) return false return value.length >= minCount } } const rules = { tags: { required: mustHaveAtLeastOne(1) } }

我个人的习惯是：只要校验逻辑超过两行，或者需要传参数，就抽成独立函数。这样代码可读性好，测试也方便，而且多个表单可以复用同一套校验逻辑。内联写法只适合那种一眼能看懂的简单判断。

注意：自定义校验函数里不要用this，Vuelidate 的校验函数是纯函数式的，this指向不确定，容易出问题。需要依赖外部状态时，通过闭包或者参数传入。

3. 自定义必传校验的完整实现方案

3.1 场景定义与数据结构设计

我拿一个实际做过的场景来演示：一个"项目发布"表单，包含三个必填字段——项目名称（普通文本）、技术标签（多选标签输入）、附件（文件上传）。其中技术标签和附件就是典型的"自定义必传"场景。

先定义数据结构：

import { reactive } from 'vue' const formData = reactive({ projectName: '', techTags: [], // 标签数组，每项是字符串 attachments: [] // 附件数组，每项是 { name, url, status } })

这里techTags和attachments都是数组，但"必填"的含义不同：techTags要求至少有一个标签，attachments要求至少有一个上传成功的附件（status === 'success'）。这就是为什么内置required不够用——它只看数组长度，不看内容状态。

3.2 自定义校验函数的编写

针对这两个字段，我写了两个自定义校验函数：

// 校验标签：至少一个非空字符串标签 const requiredTags = (value) => { if (!Array.isArray(value)) return false return value.some(tag => typeof tag === 'string' && tag.trim() !== '') } // 校验附件：至少一个上传成功的附件 const requiredAttachments = (value) => { if (!Array.isArray(value)) return false return value.some(item => item && item.status === 'success' && item.url) }

注意requiredTags里用了some而不是length > 0，因为标签数组里可能存在空字符串（用户误操作留下的），用some加trim判断能过滤掉这种脏数据。requiredAttachments则明确要求status === 'success'且有url，确保附件是真的上传成功了，而不是还在上传中或者上传失败。

把这两个函数接入规则：

import { useVuelidate } from '@vuelidate/core' import { required, minLength } from '@vuelidate/validators' const rules = { projectName: { required, minLength: minLength(2) }, techTags: { required: requiredTags }, attachments: { required: requiredAttachments } } const v$ = useVuelidate(rules, formData)

这里有个细节：techTags和attachments的规则 key 都叫required，但值是自定义函数。Vuelidate 不关心 key 叫什么，它只关心值是不是函数。所以你可以把自定义校验挂在required这个 key 下，也可以叫customRequired，效果一样。我习惯挂在required下，因为语义清晰，而且模板里用v$.techTags.required.$invalid判断时更直观。

3.3 校验触发时机的控制

Vuelidate 默认的校验触发时机是"值变化时校验"，但实际体验中，用户刚打开表单什么都没填，所有字段就飘红报错，体验很差。所以需要控制触发时机。

Vuelidate 提供了$touch()方法，配合$invalid和$dirty使用：

// 提交时统一触发校验 const handleSubmit = async () => { const isValid = await v$.value.$validate() if (!isValid) { // 校验失败，滚动到第一个错误字段 return } // 校验通过，提交数据 }

模板里判断错误显示：

<div class="form-item"> <label>技术标签</label> <TagInput v-model="formData.techTags" @blur="v$.techTags.$touch()" /> <span v-if="v$.techTags.required.$invalid && v$.techTags.$dirty" class="error"> 请至少添加一个技术标签 </span> </div>

关键点是v$.techTags.$dirty——只有字段被"触碰"过（用户操作过）才显示错误，避免初始状态就报错。$touch()在blur事件里调用，用户离开字段时才标记为已触碰。

实操心得：对于自定义组件（比如标签输入、文件上传），blur事件不一定能正常冒泡，需要在组件内部emit('blur')，父组件再调用$touch()。我踩过这个坑，标签组件里输入框的 blur 被组件根元素拦截了，导致错误提示一直不显示，排查了半天。

3.4 异步校验的处理

有些必传校验需要异步判断，比如"附件必须上传完成"这个状态，可能需要调接口确认。Vuelidate 支持异步校验函数，返回 Promise 即可：

const requiredAttachmentsAsync = async (value) => { if (!Array.isArray(value) || value.length === 0) return false // 模拟调接口确认附件状态 const results = await Promise.all( value.map(item => checkAttachmentStatus(item.id)) ) return results.some(status => status === 'success') }

异步校验要注意两点：一是$validate()返回的是 Promise，提交时要await；二是异步校验期间要有 loading 状态，避免用户重复提交。我一般会在提交按钮上加:loading="v$.$pending"，Vuelidate 的$pending属性会反映是否有校验正在进行。

4. 实操过程中的关键细节与避坑

4.1 自定义校验函数的返回值陷阱

Vuelidate 对校验函数的返回值有明确要求：返回false表示校验失败，返回true表示通过，返回其他值（包括undefined）会被当作失败处理。这个规则听起来简单，但实际写的时候很容易踩坑。

比如下面这个函数：

// 错误写法 const requiredTags = (value) => { if (!Array.isArray(value)) return // 返回 undefined，被当作失败 value.length > 0 // 没有 return，返回 undefined }

这个函数有两个问题：一是!Array.isArray(value)时直接return，返回undefined，Vuelidate 会判定失败，虽然结果"碰巧"对了，但逻辑不清晰；二是最后一行没有return，函数返回undefined，永远判定失败。正确写法必须显式返回布尔值：

// 正确写法 const requiredTags = (value) => { if (!Array.isArray(value)) return false return value.length > 0 }

注意：如果你的校验函数里有if分支，确保每个分支都有明确的return true或return false，不要依赖隐式的undefined。我见过有人写if (condition) return true，然后忘了写return false，导致校验永远通过，线上出了数据问题。

4.2 数组类型字段的响应式问题

Vue 3 的响应式系统对数组的处理有个细节：直接修改数组的length或者通过索引赋值，在某些情况下不会触发 Vuelidate 的重新校验。比如：

// 可能不触发校验 formData.techTags[0] = 'Vue' formData.techTags.length = 0 // 推荐写法，确保触发 formData.techTags = ['Vue'] formData.techTags = []

Vuelidate 内部依赖 Vue 的响应式追踪，数组的变异方法（push、splice、pop等）能正常触发，但直接赋值索引或修改length在 Vue 3 里虽然也是响应式的，但和 Vuelidate 的追踪机制配合时偶尔会有延迟。我的经验是：对数组字段做整体替换，而不是局部修改，这样最稳妥。

4.3 多个自定义校验的优先级

一个字段可能挂多个校验规则，比如techTags既要必填，又要限制最多 5 个：

const rules = { techTags: { required: requiredTags, maxTags: (value) => !Array.isArray(value) || value.length <= 5 } }

Vuelidate 会依次执行所有规则，只要有一个失败，$invalid就是true。但错误提示的显示顺序需要注意：模板里如果同时判断v$.techTags.required.$invalid和v$.techTags.maxTags.$invalid，两个错误可能同时显示，用户会困惑。我的做法是按优先级显示，只显示第一个错误：

<span v-if="v$.techTags.required.$invalid && v$.techTags.$dirty" class="error"> 请至少添加一个技术标签 </span> <span v-else-if="v$.techTags.maxTags.$invalid && v$.techTags.$dirty" class="error"> 技术标签最多 5 个 </span>

用v-else-if确保同一时间只显示一个错误，用户体验更清晰。

4.4 表单重置时的校验状态清理

表单提交成功后通常要重置，但 Vuelidate 的校验状态不会自动清理，需要手动调$reset()：

const handleReset = () => { formData.projectName = '' formData.techTags = [] formData.attachments = [] v$.value.$reset() }

$reset()会把所有字段的$dirty、$touched、$invalid等状态重置为初始值。如果不调用，重置后字段可能还显示着之前的错误提示，用户会以为没重置成功。这个坑我在项目里踩过一次，测试同学提了个"重置按钮无效"的 bug，排查后发现是校验状态没清。

5. 常见问题排查与速查表

5.1 校验不生效的排查思路

自定义校验不生效，通常有这几个原因，按排查顺序列一下：

我遇到最多的是第一条和第二条。规则 key 拼写错误这种低级问题，在字段多的时候特别容易发生，建议用 TypeScript 或者把 key 抽成常量，减少手误。

5.2 自定义组件校验的通信问题

自定义组件（标签输入、文件上传、富文本）做校验时，最大的问题是组件内部的值变化没有正确同步到formData。比如标签组件，用户输入后按回车，组件内部维护了一个数组，但没有emit更新到父组件的formData.techTags，导致 Vuelidate 拿到的还是旧值。

解决方案是确保组件用v-model正确双向绑定：

<TagInput v-model="formData.techTags" />

组件内部：

const props = defineProps(['modelValue']) const emit = defineEmits(['update:modelValue']) const addTag = (tag) => { const newTags = [...props.modelValue, tag] emit('update:modelValue', newTags) // 必须 emit，否则父组件值不更新 }

关键点是每次修改都 emit 新数组，而不是直接修改props.modelValue。直接修改 props 是 Vue 的反模式，而且不会触发父组件的响应式更新，Vuelidate 自然也不会重新校验。

5.3 性能问题的排查

表单字段多、校验逻辑复杂时，可能会遇到输入卡顿。Vuelidate 默认每次值变化都校验，如果校验函数里有复杂计算或异步请求，就会拖慢输入响应。

优化手段有两个：一是防抖，二是延迟校验。防抖可以用 lodash 的debounce包裹校验函数，但更推荐用 Vuelidate 的$lazy或者手动控制触发时机：

// 只在 blur 时校验，而不是每次输入 const rules = { projectName: { required, minLength: minLength(2) } } // 模板里不绑定 input 事件，只绑定 blur

Vuelidate 本身没有内置防抖，但可以通过$touch()的调用时机来控制。我的做法是：普通文本字段在blur时校验，数组类字段在值变化时校验（因为数组变化频率低），这样兼顾体验和性能。

5.4 错误提示的国际化与动态文案

自定义校验的错误提示往往需要动态生成，比如"至少添加 N 个标签"，N 是变量。Vuelidate 本身不管理错误文案，文案由你在模板里写。如果项目有多语言需求，建议把文案抽成配置：

const errorMessages = { techTags: { required: '请至少添加一个技术标签', maxTags: (max) => `技术标签最多 ${max} 个` } }

模板里引用：

<span v-if="v$.techTags.required.$invalid && v$.techTags.$dirty"> {{ errorMessages.techTags.required }} </span>

这样文案集中管理，改起来方便，也便于接入国际化方案。

6. 几个提升开发体验的实用技巧

6.1 把校验规则抽成独立模块

表单字段多了之后，rules对象会变得很长，混在组件里可读性差。我的做法是把校验规则抽到单独的文件：

// validators/projectForm.js import { required, minLength } from '@vuelidate/validators' export const requiredTags = (value) => { if (!Array.isArray(value)) return false return value.some(tag => typeof tag === 'string' && tag.trim() !== '') } export const requiredAttachments = (value) => { if (!Array.isArray(value)) return false return value.some(item => item && item.status === 'success' && item.url) } export const projectFormRules = { projectName: { required, minLength: minLength(2) }, techTags: { required: requiredTags }, attachments: { required: requiredAttachments } }

组件里直接引入：

import { projectFormRules } from '@/validators/projectForm' const v$ = useVuelidate(projectFormRules, formData)

这样校验逻辑和组件解耦，方便单元测试，也方便其他表单复用。

6.2 用 TypeScript 约束校验函数类型

如果项目用 TypeScript，可以给校验函数加类型约束，避免返回值类型错误：

type Validator = (value: unknown) => boolean | Promise<boolean> export const requiredTags: Validator = (value) => { if (!Array.isArray(value)) return false return value.some(tag => typeof tag === 'string' && tag.trim() !== '') }

这样写的时候，如果忘了return或者返回了非布尔值，TypeScript 会直接报错，把问题挡在编译期。

6.3 校验函数的单元测试

自定义校验函数是纯函数，非常适合单元测试。用 Vitest 或 Jest 写几个用例：

import { describe, it, expect } from 'vitest' import { requiredTags, requiredAttachments } from '@/validators/projectForm' describe('requiredTags', () => { it('空数组返回 false', () => { expect(requiredTags([])).toBe(false) }) it('有非空标签返回 true', () => { expect(requiredTags(['Vue'])).toBe(true) }) it('只有空字符串标签返回 false', () => { expect(requiredTags(['', ' '])).toBe(false) }) it('非数组返回 false', () => { expect(requiredTags(null)).toBe(false) }) })

这几个用例覆盖了正常、边界、异常三种情况，跑一遍就能确认校验逻辑没问题。我一般在写完校验函数后立刻补测试，比在页面上手动点来点去高效得多。

6.4 调试 Vuelidate 状态的小技巧

Vuelidate 的状态对象v$结构比较深，调试时不容易看清。可以在开发环境把它挂到window上：

if (import.meta.env.DEV) { window.__v$ = v$ }

然后在浏览器控制台里直接__v$.techTags.required.$invalid查看状态，比在 Vue DevTools 里一层层点开快得多。这个技巧在排查"为什么校验没触发"时特别有用，能快速定位是值没更新还是规则没匹配。

7. 关于这套方案的一些个人体会

用 Vuelidate 做自定义必传校验，核心其实就三件事：写对校验函数、接对响应式数据、控对触发时机。校验函数要显式返回布尔值，别依赖隐式undefined；响应式数据要用reactive或ref包裹，数组操作尽量整体替换；触发时机用$touch()和$dirty配合，避免初始状态就报错。

我踩过最深的坑是自定义组件的值同步问题。标签组件内部维护了数组，但忘了emit更新，导致 Vuelidate 拿到的永远是空数组，校验一直失败，但界面上标签明明显示着。排查了半天才意识到是组件通信的问题，不是校验逻辑的问题。所以如果你用自定义组件做表单字段，第一件事就是确认v-model双向绑定是通的，值能正确同步到formData。

另外，校验规则抽成独立模块这个习惯，强烈建议养成。一开始可能觉得麻烦，但字段一多、表单一变，你就会感谢自己当初抽出来了。校验逻辑和组件解耦后，改规则不用动组件，测试也好写，复用也方便。

最后分享一个小技巧：如果某个字段的校验逻辑特别复杂，与其硬写成一个函数，不如拆成多个小函数组合。比如"附件必传"可以拆成"数组非空"和"至少一个上传成功"两个判断，分别测试，最后组合。这样每个函数都简单，出问题也好定位。校验这东西，越简单越可靠，别为了炫技把逻辑写得太绕。