NextJS图片上传API中req参数为undefined的调试求助

1. 先排查API路由基础结构错误 #

后端pages/api/image/index.ts的handler函数如果出现req为undefined，最常见的原因是参数顺序或导出方式错误。Pages Router的API路由必须遵循(req, res)的参数顺序，且需正确导出默认函数：

// pages/api/image/index.ts
import type { NextApiRequest, NextApiResponse } from 'next';

// 确保参数顺序是req在前，res在后
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  console.log(req); // 现在应能正常打印req对象
  if (req.method === 'POST') {
    // 后续逻辑
    res.status(200).json({ msg: "请求正常" });
  } else {
    res.setHeader('Allow', ['POST']);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

如果之前写成(res, req)，就会导致req被赋值为res，原本的req变成undefined。

2. 修复FormData请求的处理逻辑 #

Next.js Pages Router默认不支持解析multipart/form-data类型的请求（也就是文件上传的FormData），必须禁用默认的body解析器，并使用第三方库处理：

步骤1：安装依赖 #

npm install formidable @types/formidable

步骤2：修改API路由 #

// pages/api/image/index.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import formidable from 'formidable';
import fs from 'fs';

// 禁用默认body解析，避免与formidable冲突
export const config = {
  api: {
    bodyParser: false,
  },
};

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

  const form = formidable({ multiples: false }); // 单文件上传配置

  try {
    // 解析FormData
    const { fields, files } = await new Promise((resolve, reject) => {
      form.parse(req, (err, fields, files) => {
        if (err) reject(err);
        resolve({ fields, files });
      });
    });

    console.log('表单字段:', fields);
    console.log('上传文件:', files);

    // 示例：读取文件内容（后续可写入数据库或云存储）
    const imageFile = files.image as formidable.File;
    const fileBuffer = fs.readFileSync(imageFile.filepath);

    // 写入数据库逻辑...

    res.status(200).json({ 
      message: '图片上传成功', 
      filename: imageFile.originalFilename 
    });
  } catch (err) {
    console.error('解析表单失败:', err);
    res.status(500).json({ error: '图片上传失败' });
  }
}

3. 修正前端请求代码 #

前端手动设置请求头会破坏FormData的自动边界（boundary），导致后端无法解析，需移除自定义的Content-Type：

// pages/uploadImage.tsx
const handleImageUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
  const file = e.target.files?.[0];
  if (!file) return;

  const formData = new FormData();
  formData.append('image', file); // 对应后端fields.image

  try {
    const response = await fetch('/api/image', {
      method: 'POST',
      body: formData,
      // 不要手动设置Content-Type，浏览器会自动添加正确的multipart/form-data及boundary
    });

    if (!response.ok) throw new Error('上传失败');
    const data = await response.json();
    console.log('上传成功:', data);
  } catch (err) {
    console.error('上传出错:', err);
  }
};

4. 其他排查点 #

• 检查是否存在自定义API中间件（如pages/api/_middleware.ts），如果中间件未正确传递req，也可能导致req为undefined；
• 确认API路由路径与前端请求路径一致（前端请求/api/image，后端文件必须是pages/api/image/index.ts）；
• 若使用Next.js 13+ App Router，API路由写法需改为Route Handler模式，直接用Request.formData()解析：

  // app/api/image/route.ts
  import { NextResponse } from 'next/server';
  import { writeFile } from 'fs/promises';
  import { join } from 'path';
  
  export async function POST(request: Request) {
    const formData = await request.formData();
    const file = formData.get('image') as File;
  
    if (!file) {
      return NextResponse.json({ error: '未选择文件' }, { status: 400 });
    }
  
    const bytes = await file.arrayBuffer();
    const buffer = Buffer.from(bytes);
    const savePath = join(process.cwd(), 'public', 'uploads', file.name);
    await writeFile(savePath, buffer);
  
    return NextResponse.json({ message: '上传成功', filename: file.name });
  }
  

内容的提问来源于stack exchange，提问作者engineer-x