表单别只会报错：vibe 项目的表单校验实战

先说清楚：这篇指南管什么、不管什么

表单是 vibe 项目里最容易被 AI 生成、也最容易被用户骂的地方。一个注册表单、一个发布表单、一个结算表单，表面上只是几个输入框，实际上藏着一整套判断：什么算填对了、什么时候提醒、提醒的话怎么写、错了能不能改、改完要不要重新填整张表。AI 生成表单时最常见的问题不是样式丑，而是校验逻辑要么太松（什么都放行，脏数据直接进库），要么太严（处处报错，用户填到一半就放弃了）。本篇讲的就是这套事：字段怎么定规则、错误什么时候出现、错误文案怎么写、前后端校验怎么分工、以及怎么用测试守住这些规则。

先划界，避免和站内已有的邻近指南混淆。报错与空状态指南讲的是出错界面整体怎么写，本篇只聚焦表单这一种场景的校验时机与文案；登录设备与会话管理讲的是登录后的会话安全，本篇不讲会话；文件上传指南讲的是传文件时的大小与格式限制，本篇只在“文件字段也是表单字段”这一点上交汇，不展开上传管线。本篇的示例产品“青禾记账”（一个虚构的个人记账应用）和人物“阿哲”（虚构的独立开发者）均为举例用，不是真实产品和真实用户，代码片段均为示意写法，讲的是规则与分工，不是某个框架的官方推荐写法。

第一原则：校验是帮用户填对，不是抓用户填错

做表单校验之前，先把心态摆正：校验的目的是让用户用最少的力气提交一份正确的数据，而不是证明用户填错了。这个心态会直接决定很多细节。比如手机号字段，是只允许 11 位数字、还是允许带空格和横杠再由程序清洗？从“抓错”的心态出发，你会写一条“格式不正确”的报错；从“帮填对”的心态出发，你会先把用户输入里的空格和横杠去掉再判断，实在不对再提示。同样，金额字段是只接受“12.50”这种标准写法，还是也接受“12.5”“￥12.50”再由程序归一化？每多接受一种合理写法，用户就少一次被报错打断的挫败感。

这个原则还有一个推论：能不让用户填的，就不要让用户填。国家、城市、币种这类有固定选项的字段，用选择器而不是自由输入；日期用日期选择器而不是让用户猜“2026/10/30”还是“30-10-2026”；可以从已有数据推导的字段（比如根据手机号归属地默认地区）就先帮用户填好、允许他改。AI 生成表单时最容易犯的错，就是把所有字段都做成自由输入框，然后再用一堆校验规则去收拾自由输入带来的烂摊子。先收窄输入方式，再谈校验规则，工作量会少一半。

第二原则：规则要写在三个地方，而且三处必须一致

一份表单的校验规则，实际上存在于三个地方：前端的即时校验、后端的最终校验、以及数据库或业务层的约束。这三处必须一致，否则一定会在某个时刻互相打架：前端说可以、后端说不行，用户就会看到“明明都填对了，提交却失败了”这种最让人恼火的体验；或者前端拦住了、后端没拦，懂行的用户绕过前端直接调接口，脏数据就进库了。所以规则的正确分工是：前端校验负责体验（早提醒、少打断），后端校验负责安全（最终裁决、不信任任何前端传来的数据），数据库约束负责兜底（唯一性、非空、外键这类底线）。

落地时最实用的做法是：把规则写成一份字段清单，每行写清楚字段名、类型、必填与否、长度与格式、取值范围、唯一性、错误文案。这份清单就是前端、后端和测试三方的共同依据，改规则时先改清单，再同步到三处代码。清单里还要写清楚“边界值”：比如用户名长度是 2 到 20 个字符，那么 1 个字符、2 个字符、20 个字符、21 个字符分别应该是什么结果，测试用例就按这四个边界值来写。很多校验 bug 不是规则本身错了，而是边界值没人说清楚，前端按“小于 20”写、后端按“小于等于 20”写，差一个字符就是一个线上问题。

还有一类规则特别容易在前后端之间脱节：需要查库才能判断的规则，比如用户名是否已被占用、优惠码是否有效、库存是否足够。这类规则前端只能做“建议性检查”（比如输入完后异步查一下、提前告诉用户可能有问题），最终结论必须以后端提交时的检查为准，并且要把“提交时刚好被别人抢先了”这种情况的文案也准备好。用户最不能接受的不是“这个名字已被占用”，而是“刚才还说可以用，提交时又说不行，而且不告诉我为什么”。

第三原则：错误出现的时机，比错误本身更重要

同样一条错误信息，出现的时机不同，用户的感受完全不同。表单校验的时机通常有四种：输入时实时校验、失焦时校验、提交时统一校验、以及提交后服务端返回校验。没有一种时机是万能的，正确的做法是按字段类型搭配使用。格式类规则（比如邮箱有没有 @、手机号有几位）适合失焦时提醒：用户刚填完一个字段、还没走到下一个字段时告诉他，比等到提交时一次性甩出十条错误要友好得多。实时校验要慎用：用户刚敲第一个字符就报“格式不正确”，等于在用户还没写完时就打断他，这种打断比没有校验更糟。实时校验只适合两种情况：密码强度这种用户需要边输边调整的场景，以及字符计数这种纯提示、不算报错的场景。

提交时统一校验仍然是必须的，因为总有用户会跳过某些字段、或者用自动填充一次性填完整张表。提交时的错误处理要做到三件事：第一，页面自动滚动到第一个错误字段并聚焦，让用户不用自己去找；第二，错误汇总只列出“有几个问题、分别在哪个字段”，不要把整张表的错误文案在顶部再重复一遍；第三，提交失败后已经填对的字段必须保留，用户只需要改错的那几项，而不是整张表重填。第三条是 AI 生成表单最容易丢的一条：很多 AI 生成的表单在提交失败后会把整张表清空，用户填了十分钟的东西一秒归零，这种体验的流失率比任何文案问题都高。

还有一个时机的细节：不要在用户还没碰过的字段上显示错误。很多表单一打开就满屏红字，原因是校验在页面加载时就全量跑了一遍。正确的做法是“ touched 才校验”：只有用户访问过、或者提交过一次的字段，才显示它的错误状态。这个规则听起来小，但它决定了用户对表单的第一印象：是“一张等着我填的表”，还是“一张已经在指责我的表”。

第四原则：错误文案要说人话、指明位置、给出改法

错误文案有三个检验标准，缺一个都不合格。第一，说人话：不要写“无效输入”“参数错误”“校验失败”这种只有开发者看得懂的词，要写“手机号应该是 11 位数字”“密码至少需要 8 位，包含字母和数字”。第二，指明位置：错误信息要出现在对应字段旁边，并且字段本身要有视觉标识（边框变色、图标提示），不要只在页面顶部写一句“表单有误”，让用户自己猜是哪个字段。第三，给出改法：不只说错在哪，还要说怎么改对，比如“用户名已被使用，试试‘阿哲 2026’或者换一个名字”“结束日期不能早于开始日期，请检查两个日期”。

文案还要避免两个极端。一种是太技术化：“正则表达式不匹配”“字段长度超出约束”，用户看不懂、也不知道该怎么办。另一种是太含糊：“请检查输入”“出了点问题”，用户看懂了每个字，但还是不知道该改什么。检验文案的方法很简单：找一个没参与开发的朋友，把报错截图给他看，问他“你知道该改哪里、改成什么样吗”，如果他答不上来，文案就不合格。另外，文案里不要责备用户：不要写“你输入错了”“你忘记填写”，改成中性的“这个字段还需要填写”“这里需要 11 位数字”。语气上的这一点差别，对用户的感受影响比想象中大。

密码字段值得单独说一句。密码校验最常见的反模式是：把所有规则一次性列出来（长度、大小写、数字、特殊字符），用户每改一次就发现还有下一条。更好的做法是边输边给清单打勾：满足一条就勾一条，用户一眼就知道还差哪条。以及，密码确认字段不要只在提交时才比对，失焦时就比对一次，能省掉很多“提交失败才发现两次输入不一致”的挫败。还有，永远不要在密码错误时提示“密码过于简单”之外的具体信息，更不要提示“你的旧密码是……”这类会泄露信息的内容。

第五原则：用测试守住规则，而不是靠人工每次点一遍

表单规则一旦超过十个字段，靠人工每次发布前点一遍就不现实了，测试必须跟上。表单校验的测试用例可以按一张固定的表来生成：每个字段准备四类用例——合法值、边界值、非法值、空值；再加上三类跨字段用例——字段之间的依赖（结束日期晚于开始日期）、需要查库的规则（用户名占用）、以及提交失败后已填数据的保留情况。这张表写出来后，测试代码基本就是按表填空，AI 生成测试用例时也可以直接按这张表来生成，而不是让它自由发挥。

测试里最容易漏掉的两类，值得单独提醒。第一类是“自动填充和粘贴”：浏览器自动填充、密码管理器填充、从别处复制粘贴过来的内容（常常带有多余空格或换行），这些输入路径的校验行为和手工输入可能完全不同，上线前至少要手动测一次。第二类是“网络失败和重复提交”：提交按钮在请求发出后要立刻禁用、防止用户连点造成重复提交；网络失败后要明确告诉用户“没有提交成功，请再试一次”，而不是让用户猜到底有没有提交成功。重复提交在支付和报名类表单里是真金白银的问题，值得在清单里单独列一项。

最后是无障碍这个经常被 AI 生成表单忽略的维度：错误信息不能只靠颜色区分（红字对色盲用户不友好），必须同时有文字和图标；错误字段要能被屏幕阅读器读到，错误提示要和字段用程序化的方式关联起来，而不是只在视觉上放在旁边；键盘用户要能通过 Tab 顺序走到每一个错误字段。这些要求不是“加分项”，而是表单能不能被所有用户使用的底线。上线前用键盘从头到尾走一遍表单、再用屏幕阅读器听一遍错误提示，花不了半小时，但能挡住一整类用户投诉。

第六原则：多步骤表单，每一步都要能回头、能保存

字段一多，表单往往会被拆成多个步骤：基本信息、详细信息、确认提交。对多步骤表单，校验规则要按步骤切分：当前步骤只校验当前步骤的字段，不要因为后面步骤还没填就拦住用户前进；但也不能等到最后一步才一次性校验前面所有步骤，那样用户要一路回翻才能改。比较好的做法是：每步前进时校验本步，允许用户随时回头改前面步骤的内容，改完之后如果影响了后面的步骤（比如前面改了地区、后面可选的服务列表变了），要明确提示用户“前面的修改影响了后面的选项，请检查”，而不是静默地把后面的选择清空。

多步骤表单还有一个必须做的功能：中途保存。用户填到第三步时浏览器崩了、手机没电了、被电话打断了，回来发现要从第一步重填，流失几乎是必然的。保存可以很轻量：每步完成后把已填内容存到本地，恢复时先问用户“检测到上次未提交的内容，是否继续”，而不是不打招呼就直接恢复。本地保存要注意隐私边界：涉及身份证、银行卡这类敏感信息的步骤，宁可不保存、或者只保存非敏感部分，安全比便利更重要。这个取舍要在产品里明确告诉用户，而不是替用户默认。

上线前检查清单

上线前按这张清单逐项打勾：字段清单已写好，前后端和数据库三处规则一致、边界值明确；输入方式已收窄，能选的不让自由填、能推导的先帮用户填好；校验时机已搭配，格式类失焦提醒、密码类边输边提示、提交时统一校验且自动定位到第一个错误字段；未触碰的字段不显示错误；提交失败后已填对的字段全部保留；每条错误文案都通过了“说人话、指明位置、给出改法”三项检验；需要查库的规则以后端提交时为准、且准备了“提交时刚被占用”的文案；提交按钮防重复点击、网络失败有明确提示；自动填充和粘贴路径已手动测过；测试用例覆盖每个字段的合法值、边界值、非法值、空值和跨字段依赖；错误提示不只靠颜色、有文字和图标、键盘和屏幕阅读器可达。这张清单上的任何一项缺失，都会在用户第一次认真填表时以流失的形式找回来。