Mantine表单库中Zod自定义路径校验错误丢失问题解析

在Mantine表单库与Zod校验库的集成使用过程中，开发者可能会遇到一个隐蔽但影响较大的问题：当使用Zod的refine方法进行自定义路径校验时，错误信息可能会被意外丢弃。本文将深入分析该问题的成因、影响范围及解决方案。

问题现象

当开发者尝试在Mantine表单中使用Zod的refine方法进行复杂校验，并通过path参数指定错误路径时，例如：

const schema = z.object({
  first: z.string(),
  second: z.string(),
}).refine(() => false, { path: 'first' });

尽管校验逻辑明确返回了错误，但通过form.validate()方法却无法获取到预期的错误信息。这种问题在需要精细化错误处理的场景下尤为突出。

技术背景

Mantine表单库提供了与Zod校验库的无缝集成能力，通过zodResolver桥接器将Zod的校验结果转换为Mantine可识别的错误格式。然而，在处理自定义路径错误时，当前的实现存在以下关键点：

1. 错误过滤机制：Mantine在校验时会检查错误路径是否与当前字段路径匹配
2. 路径匹配逻辑：默认只处理直接关联的字段错误

根本原因

问题核心在于Mantine的validate-field-value.ts实现中，对错误路径的处理过于严格。当Zod通过refine方法返回一个带有自定义path的错误时，Mantine的路径匹配算法无法正确识别这种"跨字段"的错误关联。

特别是在使用mode: 'uncontrolled'模式时，这个问题会更加明显，因为该模式下表单不会自动捕获所有的校验错误。

解决方案

临时解决方案

目前可行的临时方案是通过额外的状态管理来保存校验错误：

const [errors, setErrors] = useState<Record<string, any>>();

const form = useForm({
  mode: 'uncontrolled',
  validate: (values) => {
    const result = zodResolver(schema)(values);
    setErrors(result);
    return result;
  },
});

useEffect(() => {
  form.setErrors(errors);
}, [errors]);

长期建议

对于项目维护者，建议考虑以下改进方向：

1. 增强路径匹配逻辑，支持嵌套和自定义路径
2. 提供更灵活的校验错误处理选项
3. 完善文档中关于复杂校验场景的说明

最佳实践

在使用Mantine与Zod集成时，建议开发者：

1. 对于简单校验，优先使用Zod的内置校验方法
2. 复杂校验逻辑建议拆分为多个简单校验
3. 必要时使用上述状态管理方案作为过渡
4. 关注Mantine的版本更新，该问题可能会在后续版本中得到官方修复

总结