Spring MVC 多檔案上傳完整配置與 Controller 實戰

Spring MVC 檔案上傳核心在於 MultipartResolver 處理 multipart/form-data 請求，配合 @RequestParam MultipartFile 或 MultipartHttpServletRequest 取得檔案。本文涵蓋 XML/Java Config 兩種配置、單/多檔案 Controller 寫法、大小限制與異常處理。

1. 配置 MultipartResolver

XML 配置 (傳統)

<bean id="multipartResolver"
      class="org.springframework.web.multipart.commons.CommonsMultipartResolver">
    <property name="maxUploadSize" value="10485760" /> <!-- 10MB 總大小 -->
    <property name="maxUploadSizePerFile" value="5242880" /> <!-- 5MB 單檔 -->
    <property name="defaultEncoding" value="UTF-8" />
</bean>

<!-- 超過大小限制的異常導向頁面 -->
<bean class="org.springframework.web.servlet.handler.SimpleMappingExceptionResolver">
    <property name="exceptionMappings">
        <props>
            <prop key="org.springframework.web.multipart.MaxUploadSizeExceededException">
                error/fileSizeExceeded
            </prop>
        </props>
    </property>
</bean>

Java Config (Spring 3.1+ 推薦)

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
    @Bean
    public MultipartResolver multipartResolver() {
        CommonsMultipartResolver r = new CommonsMultipartResolver();
        r.setMaxUploadSize(10_485_760L);        // 10MB
        r.setMaxUploadSizePerFile(5_242_880L);  // 5MB
        r.setDefaultEncoding(StandardCharsets.UTF_8.name());
        return r;
    }
}

2. 依賴項 (Maven)

<dependency>
    <groupId>commons-fileupload</groupId>
    <artifactId>commons-fileupload</artifactId>
    <version>1.4</version>
</dependency>
<dependency>
    <groupId>commons-io</groupId>
    <artifactId>commons-io</artifactId>
    <version>2.11.0</version>
</dependency>

3. 前端表單 (必要屬性)

<form method="POST" action="/upload" enctype="multipart/form-data">
    <input type="file" name="files" multiple /> <!-- multiple 允許多選 -->
    <button type="submit">上傳</button>
</form>

4. Controller 寫法對比

寫法 A：@RequestParam MultipartFile[] (推薦，簡潔)

@PostMapping("/upload")
public String uploadFiles(@RequestParam("files") MultipartFile[] files,
                          RedirectAttributes redirectAttrs) {
    if (files == null || files.length == 0) {
        redirectAttrs.addFlashAttribute("msg", "請選擇檔案");
        return "redirect:/uploadForm";
    }
    for (MultipartFile file : files) {
        if (file.isEmpty()) continue;
        try {
            String original = file.getOriginalFilename();
            Path dest = Paths.get("/data/uploads", original);
            Files.copy(file.getInputStream(), dest, StandardCopyOption.REPLACE_EXISTING);
            redirectAttrs.addFlashAttribute("msg", "上傳成功: " + original);
        } catch (IOException e) {
            redirectAttrs.addFlashAttribute("msg", "上傳失敗: " + e.getMessage());
        }
    }
    return "redirect:/uploadForm";
}

寫法 B：MultipartHttpServletRequest (需手動轉型，靈活)

@PostMapping("/upload2")
public String uploadViaRequest(HttpServletRequest request) {
    MultipartHttpServletRequest mpReq = (MultipartHttpServletRequest) request;
    // 單檔
    MultipartFile file = mpReq.getFile("file");
    // 多檔
    List<MultipartFile> files = mpReq.getFiles("files");
    // 其餘邏輯同寫法 A
    return "result";
}

5. 進階：直接綁定到表單物件

public class UploadForm {
    private MultipartFile[] files;
    private String description;
    // getter/setter
}

@PostMapping("/upload3")
public String uploadWithForm(@Valid UploadForm form, BindingResult binding) {
    if (binding.hasErrors()) return "uploadForm";
    // 使用 form.getFiles()
    return "success";
}

6. 常見問題與解決

7. Spring Boot 專案 (零配置)

# application.yml
spring:
  servlet:
    multipart:
      max-file-size: 5MB
      max-request-size: 10MB
      enabled: true

Spring Boot 自動配置 StandardServletMultipartResolver (內嵌容器) 或 CommonsMultipartResolver，無需額外 Bean。

1. 上一篇文章： Java 漢字轉拼音完整方案：pinyin4j 庫整合與工具類封裝
2. 下一篇文章： Java System 類核心方法實戰：時間戳、環境屬性、標準流、退出 JVM

Java 相關知識

Axis2 系列教程（一）：零配置 POJO 發布與多語言客戶端調用

Axis2 簡介 Axis2 是 Apache 基金會重寫的

Spring MVC Validator 完整實戰指南：JSR-303 標準註解、自定義驗證器、分組驗證與 AJAX 整合

前言 資料驗證是 Web 應用安全的第一道防線。Spring

Java 設計模式深度解析：原型模式

什麼是原型模式？ 原型模式屬於創建型設計模式，其核心思想是：

善用物件導向設計模式替換 Switch-Case 與 If-Else

在日常 Java 開發中，針對狀態或類型進行判斷時，swit