Java 項目遷移他機 Tomcat 上傳失效？路徑處理與異常日誌是關鍵

同一 WAR 包，原機運行正常，遷移到新機器部署後文件上傳失敗（Excel/JPG 均不可用），但數據庫交互、Excel 導出正常。典型的「環境差異導致文件 IO 失敗」場景。

排查三板斧

1. 上傳路徑是硬編碼還是相對路徑？

   // 錯誤：硬編碼絕對路徑
   String uploadPath = "D:/uploads/"; 
   
   // 正確：動態獲取項目部署路徑
   String uploadPath = request.getServletContext().getRealPath("/uploads/");
   // 或從配置文件讀取，支持環境變量覆蓋
   String uploadPath = System.getProperty("app.upload.dir", "/opt/app/uploads");

   新機器盤符、目錄結構大概率不同，硬編碼必死。
2. 目錄是否存在且進程有寫權限？
   • Linux：mkdir -p /opt/app/uploads && chown tomcat:tomcat /opt/app/uploads
   • Windows：檢查 Tomcat 服務運行用戶（通常是 SYSTEM 或指定用戶）對目標文件夾的「寫入」權限。
3. 異常被吞沒了！ 代碼中 catch (Exception e) { } 空捕獲，導致前端無提示、日誌無記錄。立即補全異常日誌：

   try {
       file.transferTo(new File(uploadPath, filename));
   } catch (IOException e) {
       log.error("文件上傳失敗: path={}, file={}", uploadPath, filename, e);
       throw new BusinessException("上傳失敗: " + e.getMessage());
   }

調試技巧

• 在新機器 Tomcat 的 webapps/項目名/WEB-INF/classes 下直接修改類文件加日誌（或熱部署 JRebel），實時觀察控制台輸出。
• 寫一個獨立的 TestUpload.jsp 只做上傳測試，隔離業務邏輯干擾。
• 檢查 catalina.out / localhost.yyyy-mm-dd.log 是否有 Permission denied、No space left、Invalid path 等明確錯誤。

避坑清單

• 上傳組件版本不一致（commons-fileupload / Servlet 3.0 @MultipartConfig）
• 磁盤空間不足（df -h / 磁盤管理器）
• 殺毒軟件攔截寫入（Windows Defender / 360）
• 路徑包含中文/特殊字符導致編碼問題

核心原則：異常不為空、路徑配置化、權限顯式授予，遷移必須成功。