Undici项目中FormData版本兼容性问题解析

在Node.js生态系统中，Undici作为现代化的HTTP/1.1客户端库，近期在其v7版本中引入了一个值得开发者注意的FormData兼容性变化。本文将深入分析该问题的技术背景、产生原因及解决方案。

问题现象

当开发者从Undici v6升级到v7后，使用全局FormData对象发送multipart POST请求时，服务端会返回"415不支持的媒体类型"错误。具体表现为请求体被错误地序列化为"[object FormData]"字符串，而非预期的multipart格式数据。

技术背景

1. Node.js的全局FormData实现：Node.js内置的FormData实现与特定版本的Undici绑定（如Node.js 22绑定的是Undici 6.20版本）
2. 版本隔离机制：当项目显式安装新版本Undici时，会出现全局FormData（旧版）与显式导入的fetch（新版）版本不匹配的情况

根本原因

问题的核心在于版本混用：

• 使用全局FormData（来自Node.js内置的Undici 6.20）
• 同时使用显式导入的Undici 7.0的fetch方法 这两个版本间的FormData实现存在序列化差异，导致请求体处理异常。

解决方案

正确做法：始终从undici包中显式导入FormData类

import { FormData } from 'undici'

最佳实践建议

1. 类型安全：TypeScript会正确识别类型不匹配（全局FormData不能赋值给BodyInit类型）
2. 版本一致性：确保项目中所有Undici相关组件使用相同版本
3. 开发环境检查：配置IDE和构建工具确保能捕获此类类型错误

深入理解

该问题揭示了Node.js生态中一个重要的依赖管理原则：当使用polyfill或内置实现时，需要注意其与显式安装包的版本协调。Undici作为Node.js逐渐内置的核心模块，这种版本隔离问题值得所有Node.js开发者警惕。

通过采用显式导入策略，开发者可以确保项目不受Node.js运行时内置版本变化的影响，获得更好的可维护性和跨版本稳定性。