萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> JSP 程式設計

Java SmartUpload 組件實現檔案上傳完整指南

檔案上傳兩種路徑

方案優點缺點
原生 Servlet API (Servlet 3.0+)零依賴、標準化、`request.getPart()`需手工解析 multipart、大檔案記憶體控制複雜
Apache Commons FileUpload成熟穩定、串流處理、進度監聽需額外依賴、API 較底層
SmartUploadAPI 簡潔、內建檔案類型/大小限制、自動編碼處理專案老舊、官網已關閉、不再維護
注意:SmartUpload (jspsmart.com) 專案已停止維護多年。新專案強烈建議使用 Servlet 3.0+ 內建支援或 Apache Commons FileUpload / Spring MultipartResolver。

SmartUpload 快速上手

1. 部署

  • 下載 `smartupload.jar`
  • 放入 `WEB-INF/lib/` 或 Tomcat `lib/` 目錄

2. 前端表單 (關鍵:enctype="multipart/form-data")

<form action="upload.jsp" method="post" enctype="multipart/form-data">
    圖片:<input type="file" name="pic" />
    <input type="submit" value="上傳" />
</form>

3. JSP 處理頁面 (upload.jsp)

<%@ page contentType="text/html; charset=utf-8" %>
<%@ page import="com.jspsmart.upload.*" %>
<%
    // 1. 建立 SmartUpload 實例
    SmartUpload su = new SmartUpload();
    
    // 2. 初始化 (需傳入 pageContext 或 request/response/application)
    su.initialize(pageContext); // 或 su.initialize(config, request, response)
    
    // 3. 設定限制 (可選)
    su.setMaxFileSize(1024 * 1024 * 5);      // 單檔 5MB
    su.setTotalMaxFileSize(1024 * 1024 * 20); // 總計 20MB
    su.setAllowedFilesList("jpg,jpeg,png,gif,bmp"); // 允許副檔名
    su.setDeniedFilesList("exe,bat,sh,php,jsp,asp"); // 禁止副檔名
    
    // 4. 執行上傳解析
    su.upload();
    
    // 5. 取得一般表單欄位
    String username = su.getRequest().getParameter("username");
    
    // 6. 處理上傳檔案
    com.jspsmart.upload.Files files = su.getFiles();
    for (int i = 0; i < files.getCount(); i++) {
        com.jspsmart.upload.File file = files.getFile(i);
        
        if (file.isMissing()) continue; // 未選檔案
        
        // 取得檔案資訊
        String fileName = file.getFileName();      // 原始檔名
        String fileExt = file.getFileExt();        // 副檔名
        long fileSize = file.getSize();            // 檔案大小 (bytes)
        String contentType = file.getContentType(); // MIME 類型
        
        // 儲存至伺服器 (路徑需實際存在且可寫入)
        String savePath = application.getRealPath("/uploads/") + fileName;
        file.saveAs(savePath, SmartUpload.SAVE_PHYSICAL); // SAVE_VIRTUAL 為虛擬路徑
        
        out.println("上傳成功: " + fileName + " (" + fileSize + " bytes)<br/>");
    }
%>

進階功能

多檔案上傳

<input type="file" name="photos" />
<input type="file" name="photos" />
<input type="file" name="photos" />

<%
Files files = su.getFiles();
for (int i = 0; i < files.getCount(); i++) {
    File file = files.getFile(i);
    // 同名表單欄位會產生多個 File 物件
}
%>

檔案下載

<%@ page import="com.jspsmart.upload.*" %>
<%
    SmartUpload su = new SmartUpload();
    su.initialize(pageContext);
    
    String fileName = request.getParameter("file");
    // 安全檢查:防止路徑遍歷 ../
    if (fileName != null && !fileName.contains("..")) {
        String filePath = application.getRealPath("/uploads/") + fileName;
        java.io.File f = new java.io.File(filePath);
        if (f.exists()) {
            su.download(filePath, fileName, "application/octet-stream");
            // 或 su.download(filePath, fileName, "image/jpeg", 1024); // 指定緩衝區
        }
    }
%>

常見問題排查

現代化遷移建議:Spring Boot + MultipartFile

@PostMapping("/upload")
public ResponseEntity upload(@RequestParam("file") MultipartFile file) {
    if (file.isEmpty()) return ResponseEntity.badRequest().body("檔案為空");
    
    // 驗證檔案類型、大小
    String contentType = file.getContentType();
    if (!Arrays.asList("image/jpeg", "image/png", "image/gif").contains(contentType)) {
        return ResponseEntity.badRequest().body("不支援的檔案類型");
    }
    
    // 儲存 (建議雲端儲存 S3/MinIO 或外部檔案系統)
    String fileName = UUID.randomUUID() + "." + FilenameUtils.getExtension(file.getOriginalFilename());
    Path dest = Paths.get(uploadDir, fileName);
    Files.copy(file.getInputStream(), dest);
    
    return ResponseEntity.ok("上傳成功: " + fileName);
}

配置 `application.yml`:

spring:
  servlet:
    multipart:
      max-file-size: 5MB
      max-request-size: 20MB
      enabled: true
copyright © 萬盛學電腦網 all rights reserved
問題原因與解決
檔案大小為 0 / 空指標表單缺少 `enctype="multipart/form-data"`
中文檔名亂碼確保 JSP `pageEncoding="UTF-8"`、Tomcat `URIEncoding="UTF-8"`、資料庫連線 UTF-8
儲存失敗 Permission denied目標目錄不存在或 Tomcat 執行使用者無寫入權限
大檔案上傳失敗調整 `setMaxFileSize`、`setTotalMaxFileSize`、Tomcat `maxPostSize`、HTTP 逾時
部署 WAR 後找不到檔案勿寫入 `getRealPath()` 回傳的 WAR 內部路徑,改用外部配置目錄