NextJS环境下无第三方依赖实现NodeJS文件上传的故障解决咨询

核心问题根因 #

你之前遇到的所有解析失败、文件损坏问题，本质都是两个认知偏差：

1. 把multipart/form-data的原始请求体当成了纯文件二进制：实际请求体是由固定边界符分隔的多段结构，每段包含字段名、文件名、文件类型等文本元信息，直接把整个请求流写进文件，会把分隔符、头部文本混在二进制内容里，导致文件无法正常打开。
2. 误用了第三方库专属的方法：req.files.mv()这类方法是multer、formidable等库解析完请求后，手动挂载在请求对象上的扩展能力，原生Node.js/Next.js的请求对象本身不存在这些属性，调用必然触发报错。

零依赖实现逻辑 #

现代Node.js（18+）、Next.js运行时已经原生内置了完整的multipart/form-data解析能力，完全不需要引入任何第三方库，按照两种路由模式分别实现即可。

App Router模式（Next.js 13+ 推荐） #

App Router下的API路由直接接收Web标准Request对象，该对象原生提供formData()方法，可以直接解析上传的FormData内容，无需手动切割流、处理边界符。
实现代码：

// app/api/files/route.ts
import { writeFile, mkdir } from 'fs/promises'
import path from 'path'

export async function POST(request: Request) {
  // 原生解析FormData，无任何第三方依赖
  const formData = await request.formData()
  // 取出前端append的名为'file'的文件对象
  const uploadedFile = formData.get('file') as File | null

  if (!uploadedFile) {
    return new Response(JSON.stringify({ error: '未检测到上传文件' }), { 
      status: 400,
      headers: { 'Content-Type': 'application/json' }
    })
  }

  // 原生将文件二进制转为Buffer
  const fileBuffer = Buffer.from(await uploadedFile.arrayBuffer())
  // 配置文件保存路径（可根据业务调整到存储服务路径）
  const saveDir = path.join(process.cwd(), 'public', 'uploads')
  // 确保目录存在
  await mkdir(saveDir, { recursive: true })
  const savePath = path.join(saveDir, uploadedFile.name)
  await writeFile(savePath, fileBuffer)

  return Response.json({
    success: true,
    filename: uploadedFile.name,
    size: uploadedFile.size
  })
}

注意：App Router模式下不需要额外配置，只要保证运行时是Node.js 18+版本，上述代码即可直接运行。

Pages Router模式（传统路由兼容） #

Pages Router下的API路由默认会提前解析请求体，需要先关闭内置的body解析能力，再通过原生流收集请求内容完成解析：

// pages/api/files.ts
import type { NextApiRequest, NextApiResponse } from 'next'
import { writeFile, mkdir } from 'fs/promises'
import path from 'path'

// 必须关闭Next.js默认的bodyParser，避免流被提前消费导致无法解析
export const config = {
  api: {
    bodyParser: false,
  },
}

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    res.status(405).end('Method Not Allowed')
    return
  }

  // 收集完整的请求二进制流
  const chunks: Buffer[] = []
  for await (const chunk of req) {
    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
  }
  const rawRequestBuffer = Buffer.concat(chunks)

  // 提取请求中的multipart边界标识
  const contentType = req.headers['content-type'] || ''
  const boundaryMatch = contentType.match(/boundary=(.*)$/)
  if (!boundaryMatch) {
    res.status(400).json({ error: '非multipart/form-data格式请求' })
    return
  }
  const boundary = boundaryMatch[1]

  // 原生构造FormData结构完成解析
  const formData = new FormData()
  const mockBlob = new Blob([
    Buffer.from(`--${boundary}\r\n`),
    rawRequestBuffer
  ], { type: contentType })
  formData.set('file', mockBlob)

  // 取出文件内容并保存
  const uploadedFile = formData.get('file') as File
  const fileBuffer = Buffer.from(await uploadedFile.arrayBuffer())
  const saveDir = path.join(process.cwd(), 'public', 'uploads')
  await mkdir(saveDir, { recursive: true })
  const savePath = path.join(saveDir, uploadedFile.name)
  await writeFile(savePath, fileBuffer)

  res.status(200).json({
    success: true,
    filename: uploadedFile.name,
    size: uploadedFile.size
  })
}

常见操作避坑 #

• 不要直接写入原始请求流：原始请求体包含的边界符、头部元信息会混入文件二进制内容，是导致文件损坏的最常见原因。
• 不要调用req.files.mv()或req.body.mv()：这类方法是第三方库的扩展能力，原生请求对象无对应实现，调用必然抛出xxx is not a function错误。
• 不要对二进制内容做base64编码后写入：编码后的内容是文本格式，直接写入会生成单行文本文件，无法被系统识别为有效文件。
• 大文件优化：针对超过100MB的大文件，可以直接通过uploadedFile.stream()获取文件二进制流，对接fs.createWriteStream实现流式写入，避免将整个文件加载到内存占用过多资源，同样不需要任何第三方依赖。

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