Struts2 + AjaxFileUpload 上傳報 ClassNotFoundException: org.apache.commons.lang.xwork.StringUtils 解決

使用 ajaxfileupload 外掛上傳圖片，Struts2 執行鏈中拋出 ClassNotFoundException: org.apache.commons.lang.xwork.StringUtils。實為 依賴包版本衝突 / 包路徑錯誤 導致。

錯誤堆疊關鍵

java.lang.ClassNotFoundException: org.apache.commons.lang.xwork.StringUtils
    at org.apache.struts2.json.SerializationParams.<init>(SerializationParams.java:57)
    at org.apache.struts2.json.JSONResult.writeToResponse(JSONResult.java:214)
    ...

原因分析

• 異常類名 org.apache.commons.lang.xwork.StringUtils 顯示 包路徑錯誤：正確應為 org.apache.commons.lang3.StringUtils (Commons Lang 3) 或 org.apache.commons.lang.StringUtils (Commons Lang 2.x)。
• xwork 是 Struts2 內部核心包，不應出現在 commons-lang 路徑中。
• 專案中可能同時存在 commons-lang-2.x.jar 和 commons-lang3-3.x.jar，且類別載入器載入順序導致找不到預期類別。
• struts2-json-plugin 內部依賴 commons-lang3，若專案強制排除或版本不匹配會觸發此錯誤。

解決步驟

1. 檢查專案依賴樹 (Maven)：

   mvn dependency:tree | grep commons-lang
   

   確保僅保留一個版本，建議統一用 commons-lang3 (3.12.0+)。
2. 排除傳遞性依賴中的舊版：

   <dependency>
     <groupId>org.apache.struts</groupId>
     <artifactId>struts2-json-plugin</artifactId>
     <version>2.5.30</version>
     <exclusions>
       <exclusion>
         <groupId>commons-lang</groupId>
         <artifactId>commons-lang</artifactId>
       </exclusion>
     </exclusions>
   </dependency>
   

3. 統一添加 commons-lang3：

   <dependency>
     <groupId>org.apache.commons</groupId>
     <artifactId>commons-lang3</artifactId>
     <version>3.12.0</version>
   </dependency>
   

4. 清理並重建：mvn clean compile war:war，檢查 WEB-INF/lib 無 commons-lang-2.x.jar。

驗證

• 啟動專案，重現上傳操作，觀察 Console 無 ClassNotFoundException。
• 上傳成功返回 JSON，前端回調正常執行。

避坑指南

• Struts 2.5+ 強制要求 Commons Lang 3，勿混用 Lang 2.x。
• xwork 內部類不應被應用層直接引用，若程式碼中有 import org.apache.struts2.xwork.* 請移除。
• 定期執行 mvn dependency:analyze 檢測未使用/衝突依賴。

修正依賴版本衝突後，JSON 序列化恢復正常，檔案上傳功能穩定運作。