关于Zod解析工具函数的TypeScript神秘类型警告问题

问题原因 #

你遇到的警告源于TypeScript无法准确推断parseResult.error.format()返回的错误对象结构。当你使用宽泛的ZodSchema类型作为函数参数时，TypeScript丢失了与具体Schema关联的类型信息——即便运行时字段错误对象确实存在_errors属性，编译时类型系统也无法识别这一点。

解决方案 #

1. 添加泛型保留Schema类型信息 #

通过给函数添加泛型，让TypeScript关联传入的具体Schema类型，从而准确推断错误格式化后的结构：

import type { ZodSchema, ZodFormattedError } from 'zod'
import { z } from 'zod'

const testSchema = z.object({
  age: z.number(),
  username: z.string().min(1).max(24),
  imageUrl: z.string().url(),
})

const testData = {
  age: '93',
  username: 'SomeAbsurdlyLongUsername4u',
  imageUrl: 'httLCJyaWQiOiJ1c[malformedUrl]',
}

// 用泛型T关联具体的ZodSchema类型
export default function zodParse<T extends ZodSchema>({
  schema = testSchema as unknown as T,
  data = testData,
}: {
  schema: T
  data: unknown // 替换any，遵循类型安全最佳实践
}) {
  const parseResult = schema.safeParse(data)
  if (parseResult.success) {
    return { success: { data: parseResult.data } }
  }
  
  // 明确指定错误格式化结果的类型
  const parseFailure: ZodFormattedError<z.infer<T>> = parseResult.error.format()
  const errors: { [key: string]: string } = {}
  
  for (const [fieldName, fieldError] of Object.entries(parseFailure)) {
    if (fieldName === '_errors') {
      const formErrors = fieldError as string[]
      if (formErrors.length) errors.form = formErrors.join(' • ')
    } else {
      // 断言字段错误对象包含_errors属性
      const fieldWithErrors = fieldError as { _errors: string[] }
      errors[fieldName] = fieldWithErrors._errors.join(' • ')
    }
  }
  
  return { failure: { errors } }
}

2. 用类型守卫替代直接断言（更安全） #

如果想降低直接类型断言的风险，可以编写类型守卫来验证字段错误的结构：

// 类型守卫：判断对象是否符合Zod字段错误的结构
function isZodFieldError(obj: unknown): obj is { _errors: string[] } {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    '_errors' in obj &&
    Array.isArray((obj as { _errors: unknown })._errors) &&
    (obj as { _errors: unknown[] })._errors.every(item => typeof item === 'string')
  )
}

// 在循环中使用类型守卫
else {
  if (isZodFieldError(fieldError)) {
    errors[fieldName] = fieldError._errors.join(' • ')
  }
}

关键说明 #

• 泛型T extends ZodSchema让TypeScript记住传入Schema的具体类型，从而准确推断ZodFormattedError的结构。
• 将data的类型从any改为unknown，避免隐式类型转换带来的潜在问题，符合TypeScript类型安全原则。
• 类型断言/守卫是在明确告知TypeScript“我确认该值的结构符合预期”，既能消除编译时警告，又能保证运行时的正确性。

内容的提问来源于stack exchange，提问作者Jason T Szabo