SSH 框架檔案上傳 404 錯誤排查指南

在 SSH (Struts2 + Spring + Hibernate) 架構中，JSP 頁面上傳檔案時出現 404 錯誤，且僅在選擇檔案時發生，是典型的多部分請求（multipart/form-data）配置或攔截器順序問題。本文提供系統性排查步驟與解決方案。

常見原因分析

1. Struts2 multipart 最大尺寸限制：預設 `struts.multipart.maxSize` 為 2MB，超過即拋出異常導致 404。
2. 攔截器堆疊順序錯誤：`fileUpload` 攔截器必須在 `params` 攔截器之前執行。
3. 表單編碼缺失：JSP `
   ` 標籤未設定 `enctype="multipart/form-data"`。
4. Action 屬性名稱不匹配：Action 中檔案屬性需為 `File`、`String fileName`、`String contentType` 三組固定命名。
5. Spring 安全/事務攔截衝突：`OpenSessionInViewFilter` 或事務攔截器可能提前提交/關閉請求。

解決方案清單

1. struts.xml 調整 multipart 設定

<constant name="struts.multipart.maxSize" value="52428800" /> <!-- 50MB -->
<constant name="struts.multipart.parser" value="jakarta" /> <!-- 或 pell -->

2. 確認攔截器堆疊順序 (struts-default.xml 參考)

<interceptor-stack name="defaultStack">
    <interceptor-ref name="exception"/>
    <interceptor-ref name="alias"/>
    <interceptor-ref name="servletConfig"/>
    <interceptor-ref name="prepare"/>
    <interceptor-ref name="i18n"/>
    <interceptor-ref name="chain"/>
    <interceptor-ref name="debugging"/>
    <interceptor-ref name="profiling"/>
    <interceptor-ref name="scopedModelDriven"/>
    <interceptor-ref name="modelDriven"/>
    <interceptor-ref name="fileUpload"/> <!-- 必須在 params 之前 -->
    <interceptor-ref name="checkbox"/>
    <interceptor-ref name="datetime"/>
    <interceptor-ref name="multiselect"/>
    <interceptor-ref name="staticParams"/>
    <interceptor-ref name="actionMappingParams"/>
    <interceptor-ref name="params"/> <!-- 參數填充 -->
    <interceptor-ref name="conversionError"/>
    <interceptor-ref name="validation"/>
    <interceptor-ref name="workflow"/>
</interceptor-stack>

3. JSP 表單正確寫法

<s:form action="uploadAction" method="post" enctype="multipart/form-data">
    <s:file name="uploadFile" label="選擇檔案"/>
    <s:submit value="上傳"/>
</s:form>

4. Action 類別標準屬性定義

public class UploadAction extends ActionSupport {
    private File uploadFile;           // 檔案對象
    private String uploadFileFileName; // 原始檔名
    private String uploadFileContentType; // MIME 類型
    
    // Getter/Setter 略
    
    public String execute() {
        // 業務邏輯：儲存檔案、寫入資料庫等
        return SUCCESS;
    }
}

5. 除錯關鍵：啟用詳細日誌

# log4j.properties
log4j.logger.org.apache.struts2.dispatcher.multipart=DEBUG
log4j.logger.com.opensymphony.xwork2.interceptor.FileUploadInterceptor=DEBUG

觀察控制台輸出，確認：

• 請求是否到達 `FileUploadInterceptor`
• 檔案大小是否超過限制
• 暫存目錄權限是否正常

進階排查：若上述皆正確仍 404

• 檢查 `web.xml` 中 `Filter` 與 `DispatcherServlet` 的 `url-pattern` 是否攔截 `.action` 或 `/*` 導致靜態資源衝突。
• Tomcat `server.xml` 中 `` 的 `maxPostSize` 預設 2MB，需同步調大。
• 若使用 Nginx 反向代理，檢查 `client_max_body_size` 設定。
• Spring 的 `MultipartFilter` (若有) 需在 Struts2 Filter 之前註冊，或改用 Struts2 內建 multipart 處理。

最佳實務建議

1. 將檔案上傳邏輯獨立為獨立 Action/模組，避免與其他業務攔截器混淆。
2. 前端加入檔案大小/類型預檢，減少無效請求。
3. 使用 Apache Commons FileUpload 或 Servlet 3.0 `Part` API 替代 Struts2 內建處理，控制力更強。
4. 上傳目錄掛載獨立磁碟分區，設定磁碟配額防止佔滿系統盤。

系統性檢查上述配置點，多數 SSH 檔案上傳 404 問題皆可解決。關鍵在於「請求能否完整到達 Action」與「multipart 解析器參數是否足夠」。