如何使用Node.js内置fetch（非node_fetch）通过FormData上传文件？

前提条件 #

Node.js 18及以上版本（内置fetch和FormData从该版本开始稳定支持）

实现步骤与示例 #

1. 基础文件上传（异步读取文件）

通过fs/promises读取文件为Buffer，包装成Blob后添加到FormData，再用fetch发送请求：

import { readFile } from 'node:fs/promises';

async function uploadFile() {
  // 初始化FormData实例
  const formData = new FormData();

  // 添加普通表单字段（可选）
  formData.append('user_id', '123');
  formData.append('remark', '这是一张测试图片');

  // 读取文件并转换为Blob
  const fileBuffer = await readFile('./demo.jpg');
  const fileBlob = new Blob([fileBuffer], { type: 'image/jpeg' });
  // 第三个参数为上传时的文件名
  formData.append('upload_file', fileBlob, 'demo.jpg');

  // 发送POST上传请求
  try {
    const response = await fetch('https://your-upload-endpoint.com/api/upload', {
      method: 'POST',
      body: formData,
      // 无需手动设置Content-Type，fetch会自动生成带边界符的multipart/form-data头
    });

    if (!response.ok) {
      throw new Error(`上传失败，状态码: ${response.status}`);
    }

    const result = await response.json();
    console.log('上传成功:', result);
  } catch (err) {
    console.error('上传出错:', err.message);
  }
}

uploadFile();

2. 大文件上传（流式读取）

对于大文件，使用fs.createReadStream流式读取，避免占用过多内存：

import { createReadStream } from 'node:fs';

async function uploadLargeFile() {
  const formData = new FormData();

  // 直接传入文件流，同时指定文件名和MIME类型
  formData.append('large_file', createReadStream('./big-video.mp4'), {
    filename: 'big-video.mp4',
    type: 'video/mp4'
  });

  const response = await fetch('https://your-upload-endpoint.com/api/upload-large', {
    method: 'POST',
    body: formData
  });

  const result = await response.json();
  console.log('大文件上传成功:', result);
}

uploadLargeFile();

关键注意事项 #

• 无需手动设置Content-Type：当fetch的body为FormData时，会自动生成包含正确边界符的multipart/form-data请求头，手动设置可能导致上传失败
• 多文件上传：重复调用formData.append()即可添加多个文件，每个文件可指定不同的字段名
• 错误处理：务必检查response.ok判断请求是否成功，避免忽略HTTP错误状态码

内容的提问来源于stack exchange，提问作者Rex Pan