TypeScript Koa服务用koa-body接收Python上传文件遇大小超限问题求助

问题场景 #

基于TypeScript+Koa实现的服务，使用koa-body处理请求，当通过Python的requests库调用文件上传API时，出现报错：

Error: options.maxFieldsSize (20971520 bytes) exceeded, received 20987791 bytes of field data

但用Node.js或Postman调用同一API时无异常。尝试调大maxFieldsSize到3GB后，又触发NodeJS底层的512MB字符串大小限制。

根因分析 #

koa-body默认配置下，会将multipart/form-data中的文件内容直接解析为普通字段存入request.body，而非以文件流/磁盘文件的方式处理。Python requests上传文件时的请求格式，会让这种默认解析逻辑把文件内容完全加载到内存作为字段值，从而触发maxFieldsSize限制；而Node.js/Postman的请求格式会被koa-body正确识别为文件，走专门的文件处理逻辑，因此不会触发该问题。

这种内存加载文件的方式不仅会触发maxFieldsSize，还会受限于NodeJS单字符串最大512MB的限制，无法处理大文件。

解决方案 #

通过调整koa-body的配置，强制使用formidable将文件存储到磁盘而非内存，同时正确配置文件大小限制：

• 开启multipart支持，指定文件存储目录
• 配置formidable参数，设置maxFileSize并禁用内存加载文件
• 仅保留合理的maxFieldsSize用于处理普通表单字段

TypeScript配置示例 #

import Koa from 'koa';
import koaBody from 'koa-body';
import fs from 'fs';

const app = new Koa();

// 确保上传目录存在
const uploadDir = './uploads';
if (!fs.existsSync(uploadDir)) {
  fs.mkdirSync(uploadDir, { recursive: true });
}

app.use(koaBody({
  multipart: true, // 必须开启multipart格式支持
  formidable: {
    maxFileSize: 3 * 1024 * 1024 * 1024, // 设置3GB的文件大小上限
    uploadDir: uploadDir, // 文件存储到指定目录
    keepExtensions: true, // 保留原始文件扩展名
    hash: 'md5', // 可选：生成文件哈希值用于校验
    // 直接写入磁盘，避免加载文件内容到内存
    fileWriteStreamHandler: (file) => {
      return fs.createWriteStream(`${uploadDir}/${file.newFilename}`);
    }
  },
  maxFieldsSize: 10 * 1024 * 1024, // 普通表单字段上限设为10MB即可
  parsedMethods: ['POST', 'PUT', 'PATCH']
}));

// 上传API示例
app.use(async (ctx) => {
  if (ctx.path === '/api/data' && ctx.method === 'POST') {
    // 从ctx.request.files获取上传的文件信息
    const file = ctx.request.files?.firmware;
    if (file) {
      ctx.body = {
        code: 200,
        message: '上传成功',
        fileInfo: {
          name: file.originalFilename,
          path: file.filepath,
          size: file.size
        }
      };
    } else {
      ctx.status = 400;
      ctx.body = { code: 400, message: '未上传文件' };
    }
  }
});

app.listen(3000, () => {
  console.log('服务启动在 http://127.0.0.1:3000');
});

关键说明 #

• 配置后，上传的文件会被写入指定磁盘目录，而非加载到内存，彻底避开maxFieldsSize和NodeJS字符串大小限制
• 在API处理逻辑中，需要从ctx.request.files获取文件信息，而非ctx.request.body
• 确保上传目录有读写权限，避免文件写入失败

验证 #

使用你提供的Python代码测试，配置完成后即可正常上传大文件：

import requests
file_path = 'test.txt'
url = 'http://127.0.0.1:3000/api/data'
token = '1234'
headers = {
     'Authorization': 'Bearer {}'.format(token),
    }
files = {'firmware': open(file_path, 'rb')}
response = requests.post(url, headers=headers, files=files)

if response.status_code == 200:
    print('success')
else:
    print('failed', response.status_code)
print(response.json())

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