Next.js使用formidable-serverless解析表单出现TS类型不匹配报错

安全阿岳

2026-8-26

问题背景

在Next.js API路由中使用formidable-serverless解析表单数据，尝试合并fields和files的内容为单个对象存入数据库时，接连遇到TypeScript报错：

最初直接在fields对象上追加logo属性（值来自files.logo），报错：Type 'File | File[]' is not assignable to type 'string | string[]'
自定义Data接口后通过as强转对象类型，报错：Conversion of type '{ name: string | string[]; address: string | string[]; logo: formidable.File | formidable.File[]; }' to type 'Data' may be a mistake because neither type sufficiently overlaps with the other.

报错原因

第一个报错：formidable自带的Fields类型定义中，所有字段值的类型均为string | string[]，不支持挂载File类型的属性，直接修改原fields对象会触发类型不匹配。
第二个报错：自定义接口中name、address定义为单string类型，但formidable返回的所有字段、文件都存在「单值/多值数组」两种可能性，类型为T | T[]，两边类型结构没有足够重叠，TS会判定强转存在风险。另外定义的接口中address为string类型，但实际逻辑里对address做了JSON.parse，解析后是对象类型，本身也和接口定义冲突。

可行修复方案

不要直接修改formidable返回的原对象，单独提取字段做类型收窄，匹配实际业务场景的类型定义即可，全程不需要无意义的as强转。

首先根据实际业务定义数据结构，注意JSON.parse后的地址字段要对应解析后的对象类型，不要写string：

import type { Fields, Files, File } from 'formidable'

// 替换为你JSON.parse(address)后的实际地址结构
interface AddressInfo {
  province?: string
  city?: string
  detail?: string
}

interface FormSubmitData {
  name: string
  address: AddressInfo
  logo: File
}

写两个简单的工具函数，处理formidable返回值可能为数组的场景，做类型收窄（如果你的业务是多文件/多同名字段提交，跳过工具函数，直接用数组类型即可）：

// 提取单值字符串字段
const getSingleStr = (val: string | string[] | undefined): string => {
  return Array.isArray(val) ? val[0]?.trim() || '' : val?.trim() || ''
}

// 提取单上传文件
const getSingleFile = (val: File | File[] | undefined): File | null => {
  return Array.isArray(val) ? val[0] || null : val || null
}

在form.parse回调中提取字段、做合法性校验后再组装数据对象，修正后的完整回调逻辑如下：

form.parse(req, (err: Error, fields: Fields, files: Files) => {
  if (err) {
    res.status(422).end()
    resolve()
    return
  }

  // 提取字段
  const name = getSingleStr(fields.name)
  const addressStr = getSingleStr(fields.address)
  const logo = getSingleFile(files.logo)

  // 基础校验
  if (!name || !addressStr || !logo) {
    res.status(400).end()
    resolve()
    return
  }

  // 解析地址JSON，处理解析失败场景
  let address: AddressInfo
  try {
    address = JSON.parse(addressStr)
  } catch {
    res.status(400).end()
    resolve()
    return
  }

  // 组装数据，此时类型完全匹配，无需强转
  const data: FormSubmitData = {
    name,
    address,
    logo
  }

  const id = nanoid()
  db.set(id, data)
    .then(() => {
      res.status(201).end()
      resolve()
    })
    .catch(() => {
      res.status(500).end()
      resolve()
    })
})

注意事项

所有错误分支记得加resolve()和return，否则API请求会挂起超时。
尽量避免滥用as做类型强转，TS的类型校验本质是帮你提前覆盖「字段为空、字段是数组、JSON解析失败」这类边界场景，直接强转会绕过校验，线上容易出现空值报错。
如果业务是多文件上传、多同名字段提交，把接口对应字段改成数组类型，不需要用上面的单值提取工具函数即可。

内容的提问来源于stack exchange，提问作者S R