ts-rest项目中Next.js处理multipart/form-data请求的挑战与解决方案

在基于ts-rest和Next.js构建应用时，开发人员经常会遇到处理multipart/form-data类型请求的问题。本文将深入分析这一技术挑战的根源，并提供切实可行的解决方案。

问题本质分析

当开发者在ts-rest中定义multipart/form-data类型的路由契约时，Next.js默认的请求处理机制无法正确解析这种格式的数据。这是因为Next.js内置的body解析器(body-parser)并不原生支持multipart/form-data格式。

错误现象详解

开发者通常会观察到以下错误模式：

1. 前端正确构造了FormData对象并设置了正确的Content-Type头
2. 请求能够成功发送到后端
3. 后端返回Zod验证错误，提示"Expected object, received string"

这种错误表明虽然请求格式正确，但Next.js未能将multipart数据正确解析为JavaScript对象，导致验证失败。

解决方案实现

要解决这个问题，我们需要绕过Next.js默认的body解析器，并引入专门的multipart数据处理中间件。以下是具体实现步骤：

1. 禁用默认body解析器 在API路由文件中添加配置，显式禁用Next.js的body解析功能：

export const config = {
  api: {
    bodyParser: false,
  },
};

2. 引入multer中间件 multer是Node.js生态中专门处理multipart/form-data的中间件：

import multer from 'multer';
const upload = multer();

3. 创建自定义请求处理器 将multer与ts-rest的路由处理器结合使用：

export default async (req, res) => {
  upload.none()(req, null, (error) => {
    // 此时req.body已包含文本字段
    return createSingleRouteHandler(contract.endpoint, handler)(req, res);
  });
};

技术原理深入

这种解决方案之所以有效，是因为：

• multer专门设计用于解析multipart/form-data格式
• 禁用Next.js默认解析器避免了双重解析冲突
• upload.none()表示我们只处理非文件字段(文本字段)
• 解析后的数据会直接附加到req.body上，与ts-rest的验证机制兼容

最佳实践建议

1. 对于文件上传场景，可以使用multer的diskStorage或memoryStorage配置
2. 考虑添加错误处理逻辑，特别是大文件上传时的限制
3. 在生产环境中，应该添加文件类型和大小验证
4. 对于纯API项目，考虑使用专门的后端框架如Express.js，它们对multipart数据的支持更完善

通过以上方法，开发者可以成功在Next.js和ts-rest的组合中实现multipart/form-data类型请求的处理，解决常见的验证错误问题。