SpringMVC 文件上傳失敗排查：CommonsMultipartResolver 配置與使用全解析

問題現象

使用 SpringMVC + Red5 服務器進行文件上傳，Controller 中 commonsMultipartResolver.isMultipart(request) 返回 false，無法獲取上傳文件，但 request.getParameter("upload") 能獲取到文件名。手動轉型 MultipartHttpServletRequest 拋出 ClassCastException。

根本原因分析

1. MultipartResolver 未正確配置或未生效：Spring 需要在容器中註冊 MultipartResolver Bean，且 id 必須為 multipartResolver。
2. 請求未被正確解析為 Multipart：若 Resolver 未生效，HttpServletRequest 仍為原始請求，非 MultipartHttpServletRequest。
3. 表單缺少 enctype：前端 form 必須設置 enctype="multipart/form-data"。

正確配置步驟

1. Spring 配置文件中註冊 MultipartResolver

<bean id="multipartResolver" class="org.springframework.web.multipart.commons.CommonsMultipartResolver">
    <property name="defaultEncoding" value="utf-8"/>
    <property name="maxUploadSize" value="209715200"/> <!-- 200MB -->
    <property name="maxInMemorySize" value="1048576"/> <!-- 1MB -->
</bean>

關鍵點：Bean id 必須為 multipartResolver，Spring 會自動檢測此 Bean。

2. Controller 簡化寫法（推薦）

無需手動創建 Resolver，直接使用 @RequestParam("file") MultipartFile file：

@PostMapping("/upload.do")
public String upload(@RequestParam("file") MultipartFile file, HttpServletRequest request) {
    if (file.isEmpty()) {
        return "error";
    }
    try {
        String path = "/WEB-INF/upload/" + file.getOriginalFilename();
        File dest = new File(request.getServletContext().getRealPath(path));
        if (!dest.getParentFile().exists()) {
            dest.getParentFile().mkdirs();
        }
        file.transferTo(dest);
        return "success";
    } catch (IOException e) {
        e.printStackTrace();
        return "error";
    }
}

3. 前端表單必備屬性

<form action="/upload.do" method="post" enctype="multipart/form-data">
    <input type="file" name="file" />
    <input type="submit" value="上傳" />
</form>

常見坑點總結

大文件上傳建議

若文件較大（>100MB），建議：

• 使用 StandardServletMultipartResolver (Servlet 3.0+) 替代 Commons，支援非阻塞 IO。
• 前端採用分片上傳（如 Plupload、WebUploader），後端合併分片。
• 配置 Nginx/反向代理的 client_max_body_size 和超時時間。

Red5 環境特別提示

Red5 基於 Jetty/Tomcat，確保 commons-fileupload 和 commons-io 依賴版本與容器兼容。若在 Red5 插件中開發，注意類加載器隔離問題，確保 Spring 容器能掃描到配置。

核心原則：**讓 Spring 容器管理 MultipartResolver，Controller 僅接收 MultipartFile 參數**，避免手動解析請求導致的類型轉換與生命周期問題。