如何在Next.js中解析FilePond上传的图片表单数据

问题根源 #

• 手动设置Content-Type: multipart/form-data：浏览器会自动生成包含boundary的Content-Type，手动设置会破坏解析规则，导致文件被转为Blob字符串无法识别。
• Next.js API路由默认不解析multipart/form-data：原生API路由只处理JSON、urlencoded格式，需要第三方工具处理文件上传请求。
• FilePond的ondata配置错误：你手动添加的test-image字符串覆盖了实际上传的文件，导致服务器接不到有效文件数据。

客户端代码修正 #

// Component
import { FilePond, File, registerPlugin } from "react-filepond";
import FilePondPluginImageExifOrientation from 'filepond-plugin-image-exif-orientation';
import FilePondPluginImagePreview from "filepond-plugin-image-preview";
// 别忘了引入FilePond样式
import "filepond/dist/filepond.min.css";
import "filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.css";

registerPlugin(FilePondPluginImageExifOrientation, FilePondPluginImagePreview);

const Page = () => {
    const [productImages, setProductImages] = useState<File[]>([]);
    return (
        <FilePond
          allowMultiple={true}
          maxFiles={2}
          files={productImages}
          onupdateFiles={setProductImages}
          server={{
            process: {
              url: "/api/upload",
              method: "POST",
              // 移除手动设置的Content-Type，让浏览器自动处理
              // headers: {
              //   "Content-Type": "multipart/form-data"
              // },
              // 如需追加自定义字段，不要覆盖原文件
              ondata: formData => {
                formData.append('productId', '123'); // 示例自定义字段
                return formData;
              }
            }
          }}
        />
    );
};

export default Page;

服务器端处理（Next.js API路由） #

先安装依赖：

npm install formidable @google-cloud/storage
# 或
yarn add formidable @google-cloud/storage

编写API路由：

// ./pages/api/upload.ts
import { NextApiRequest, NextApiResponse } from "next";
import { IncomingForm } from "formidable";
import { Storage } from "@google-cloud/storage";
import fs from "fs";

// 禁用Next.js默认的body解析器，让formidable处理
export const config = {
  api: {
    bodyParser: false,
  },
};

// 初始化GCS客户端，建议用环境变量加载认证信息
const storage = new Storage({
  credentials: process.env.GCS_SERVICE_ACCOUNT_KEY ? JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY) : undefined,
});
const bucket = storage.bucket(process.env.GCS_BUCKET_NAME || '');

const uploadHandler = async (req: NextApiRequest, res: NextApiResponse) => {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: '只接受POST请求' });
  }

  const form = new IncomingForm({
    keepExtensions: true, // 保留文件扩展名
    maxFileSize: 5 * 1024 * 1024, // 限制单文件5MB，可按需调整
  });

  form.parse(req, async (err, fields, files) => {
    if (err) {
      return res.status(500).json({ message: '表单解析失败', error: err.message });
    }

    // 处理多文件情况，FilePond上传多文件时会返回数组
    const uploadFiles = Array.isArray(files.image) ? files.image : [files.image].filter(Boolean);
    
    if (!uploadFiles.length) {
      return res.status(400).json({ message: '未上传任何文件' });
    }

    try {
      // 批量上传到GCS
      const uploadPromises = uploadFiles.map(async (file) => {
        // 生成唯一文件名，避免重复
        const gcsFileName = `products/${Date.now()}-${file.originalFilename}`;
        const gcsFile = bucket.file(gcsFileName);

        // 流式上传文件到GCS
        await new Promise((resolve, reject) => {
          fs.createReadStream(file.filepath)
            .pipe(gcsFile.createWriteStream({
              resumable: false,
              contentType: file.mimetype,
              public: true, // 若需公开访问则设为true，私有文件可配置签名URL
            }))
            .on('finish', resolve)
            .on('error', reject);
        });

        // 返回GCS文件的公开访问URL
        return gcsFile.publicUrl();
      });

      const urls = await Promise.all(uploadPromises);
      return res.status(200).json({ message: '上传成功', urls });
    } catch (gcsErr) {
      return res.status(500).json({ message: '上传到GCS失败', error: gcsErr.message });
    } finally {
      // 清理formidable生成的临时文件，避免占用磁盘
      uploadFiles.forEach(file => fs.unlinkSync(file.filepath));
    }
  });
};

export default uploadHandler;

最佳实践 #

• 敏感信息管理：GCS的服务账号密钥、桶名等配置，通过.env.local环境变量加载，不要硬编码到代码中。
• 文件校验：客户端限制文件类型、大小，服务器端二次校验，防止恶意文件上传。
• 临时文件清理：formidable会将文件暂存到服务器临时目录，上传完成后必须删除，避免磁盘溢出。
• GCS权限配置：根据文件是否公开，设置对应的存储类和权限；私有文件可通过生成签名URL提供临时访问。
• 错误处理：添加完善的错误捕获和返回，方便前端排查问题。

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