NodeJS POST上传文件报fetch failed: object2 is not iterable

报错本质是Web标准API和Node原生模块的适配问题，两个核心触发点：

• Node 17.5+ 自带的原生fetch基于undici实现，配套的是Web标准的FormData对象，和npm上第三方form-data库的API不通用。你代码里调用的formData.getHeaders()是第三方库独有的方法，原生FormData上根本不存在这个方法，强行调用会拿到undefined，直接展开到headers里会导致请求头配置异常。另外原代码的upload函数没加async关键字，内部用await本身就会触发语法错误。
• 原生FormData的append方法只接受字符串、Blob、File等Web标准类型的值，不支持直接传入Node.js原生的fs.ReadStream流。undici在序列化表单数据时，会尝试按Web流的逻辑迭代读取传入的文件内容，拿到Node原生ReadStream后发现结构不匹配无法迭代，就抛出了object2 is not iterable的底层错误。

优先推荐第一种无额外依赖的标准写法，兼容性最好：

方案1：使用Web标准File对象包装文件（推荐） #

不要手动设置表单的Content-Type请求头，原生fetch会自动识别FormData类型，自动拼接带正确boundary的Content-Type，手动设置反而会丢失boundary导致服务端解析失败。小文件直接读成Buffer包装成File即可：

const fs = require('fs/promises');

// 补上async关键字，否则内部await会报错
async function upload(hub_entity_id, document_path) {
  const formData = new FormData();
  formData.append("type", "Document");
  formData.append("name", "ap_test_document.pdf");
  // 读取文件为Buffer，包装成Web标准File对象再传入
  const fileBuffer = await fs.readFile("ap_test_document.pdf");
  formData.append("file", new File([fileBuffer], "ap_test_document.pdf", {
    type: "application/pdf"
  }));
  formData.append("entity_object_id", hub_entity_id);

  const headers = {
    Authorization: auth_code
    // 不要加formData.getHeaders()，不要手动设置Content-Type
  };

  console.log(`Uploading document ap_test_document.pdf to hub (${hub_entity_id})`);

  const raw_response = await fetch(urls.attachments, {
    method: "POST",
    headers,
    body: formData
  });

  console.log(raw_response);
}

如果要上传大文件不想全量读进内存，可以把Node的fs流转成Web标准ReadableStream再包装成Blob传入，逻辑稍复杂，小文件场景用上面的写法足够。

方案2：使用第三方form-data库适配 #

如果你习惯用form-datanpm包的写法，需要手动引入对应包，不要用全局的原生FormData：

1. 先安装依赖：npm install form-data
2. 代码调整如下：

const fs = require('fs');
// 显式引入第三方form-data库，覆盖全局原生FormData
const FormData = require('form-data');

async function upload(hub_entity_id, document_path) {
  const formData = new FormData();
  formData.append("type", "Document");
  formData.append("name", "ap_test_document.pdf");
  formData.append("file", fs.createReadStream("ap_test_document.pdf"));
  formData.append("entity_object_id", hub_entity_id);

  const headers = {
    Authorization: auth_code,
    ...formData.getHeaders() // 第三方库才支持该方法
  };

  console.log(`Uploading document ap_test_document.pdf to hub (${hub_entity_id})`);

  const raw_response = await fetch(urls.attachments, {
    method: "POST",
    headers,
    body: formData
  });

  console.log(raw_response);
}

该方案在Node 18之前的早期版本存在兼容性问题，大文件场景建议优先评估后使用。

内容的提问来源于stack exchange，提问作者Harrison Broadbent