Flutter Multipart文件上传至Java Servlet报错：未配置多部件处理

场景：Flutter端通过http.MultipartRequest发送multipart/form-data请求，服务端Java Servlet调用request.getParts()时抛出如下异常：

java.lang.IllegalStateException: Unable to process parts as no multi-part configuration has been provided
        at org.apache.catalina.connector.Request.parseParts(Request.java:2866)
        at org.apache.catalina.connector.Request.getParts(Request.java:2834)

已确认请求的Content-Type为multipart/form-data; ...，格式正确。

核心原因 #

Servlet容器（如Tomcat）默认不会自动解析multipart请求，必须显式配置multipart处理规则，才能让容器正确解析表单字段和上传文件。

解决方法 #

方法1：使用@MultipartConfig注解（Servlet 3.0+推荐） #

在你的Servlet类上添加@MultipartConfig注解，参数可根据业务需求调整：

import javax.servlet.annotation.MultipartConfig;
import javax.servlet.http.HttpServlet;

@MultipartConfig(
    fileSizeThreshold = 1024 * 1024, // 文件大小超过1MB时写入磁盘
    maxFileSize = 1024 * 1024 * 5,    // 单个文件最大5MB
    maxRequestSize = 1024 * 1024 * 10 // 整个请求最大10MB
)
public class YourUploadServlet extends HttpServlet {
    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response) {
        try {
            Collection<Part> parts = request.getParts();
            // 处理上传的文件和表单字段
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

如果不需要大小限制，直接用空注解即可：@MultipartConfig

方法2：通过web.xml配置（传统方式） #

若不使用注解，可在项目web.xml中给目标Servlet添加<multipart-config>子元素：

<servlet>
    <servlet-name>YourUploadServlet</servlet-name>
    <servlet-class>com.yourpackage.YourUploadServlet</servlet-class>
    <multipart-config>
        <file-size-threshold>1048576</file-size-threshold> <!-- 1MB -->
        <max-file-size>5242880</max-file-size> <!-- 5MB -->
        <max-request-size>10485760</max-request-size> <!-- 10MB -->
    </multipart-config>
</servlet>

额外检查点 #

• 确保Servlet版本为3.0及以上（对应Java EE 6+），Tomcat版本需为7.0及以上。
• 不要在调用getParts()前手动调用request.getParameter()等方法，否则会导致multipart请求提前被解析，引发后续报错。

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