Form-Data 项目弃用 util.isArray 的技术迁移指南

在 Node.js 生态系统中，form-data 是一个广泛使用的库，用于处理表单数据的构建和提交。随着 Node.js 22 版本的发布，一个重要的变更影响了这个库的兼容性——util.isArray 方法被标记为运行时废弃，并计划在 Node.js 23 中完全移除。

背景分析

form-data 库在其核心代码中使用了 util.isArray 方法来检查变量是否为数组类型。这个实现方式在早期 Node.js 版本中是常见的做法，但随着 JavaScript 语言标准的演进，Array.isArray 已经成为检查数组类型的标准方法。

util.isArray 实际上是 Array.isArray 的别名，Node.js 团队决定逐步淘汰这种冗余的 API 接口，以简化核心模块并减少维护负担。这种变化体现了 Node.js 向更标准化、更精简的方向发展。

影响范围

这一变更直接影响到了 form-data 库的以下代码位置：

lib/form_data.js 第64行

当用户在使用较新版本的 Node.js 运行时，特别是升级到 Node.js 22 或更高版本时，如果继续使用依赖 util.isArray 的 form-data 版本，将会遇到运行时警告甚至错误。这尤其影响了像 fastify 这样依赖 form-data 的流行框架。

解决方案

社区贡献者已经提出了将 util.isArray 替换为 Array.isArray 的修改方案。这种替换是完全等效的，因为：

1. 两者在功能上完全一致
2. Array.isArray 是 ECMAScript 标准方法
3. 所有现代 JavaScript 环境都支持这个方法
4. 性能表现相同

升级建议

对于使用 form-data 的开发者，建议采取以下步骤：

1. 检查项目中使用的 form-data 版本
2. 确保升级到已修复此问题的版本（v2、v3 和 v4 版本线均已发布补丁）
3. 如果暂时无法升级，可以考虑在项目中添加 polyfill 或 monkey patch

技术启示

这个案例给我们带来了几个重要的技术启示：

1. API 标准化的重要性：优先使用语言标准提供的方法，而非运行时特定的实现
2. 前瞻性开发：在编写库代码时，应考虑使用最稳定、最标准的 API
3. 依赖管理：定期更新项目依赖，以获取安全修复和兼容性改进
4. 生态系统协调：开源项目需要及时响应底层运行时的变更，保持生态系统的健康

通过这次变更，我们可以看到 Node.js 生态系统如何逐步淘汰旧的 API 模式，推动开发者采用更标准化的编码实践。对于库开发者而言，这提醒我们需要持续关注运行时环境的变化，并及时调整实现策略。