Java POI 修改 Excel 儲存格樣式失效？常見原因與排查步驟

使用 Apache POI (HSSF/XSSF) 修改 Excel 儲存格樣式（如背景色）卻不生效，通常非 API 錯誤，而是細節疏漏。以下系統性排查清單：

核心程式碼回顧

HSSFWorkbook wb = new HSSFWorkbook(new FileInputStream(path));
HSSFCellStyle style = wb.createCellStyle();
style.setFillForegroundColor(HSSFColor.RED.index); // 注意：前景色
style.setFillPattern(FillPatternType.SOLID_FOREGROUND);
cell.setCellStyle(style);

常見失效原因

1. 用錯顏色屬性： setFillBackgroundColor 設定的是「背景色」（pattern 為非實心時才可見），實心填滿必須用 setFillForegroundColor。
2. 樣式重複建立： 每次 createCellStyle() 都會產生新樣式，大量儲存格會超出 Excel 樣式上限 (64k)。應共用樣式物件，或用 CellUtil.getCellStyle() 管理。
3. 未寫回檔案： 修改後必須 wb.write(new FileOutputStream(path)) 並 close()。
4. 儲存格類型衝突： 若儲存格原為公式或錯誤值，設定樣式可能不顯示，需先 cell.setCellType(CellType.STRING)。
5. 版本不匹配： .xls 用 HSSF，.xlsx 用 XSSF，混用會失效。

排查步驟

1. 確認程式碼無編譯/執行期例外。
2. 在 IDE 除錯模式檢查 style 物件屬性是否如預期。
3. 輸出檔案後用 Excel 開啟，檢查「儲存格格式」對話框中「填滿」頁籤是否套用。
4. 嘗試最小化範例：新建一個只有幾行的測試檔，隔離問題。

最佳實踐

• 統一使用 Workbook、Sheet、Row, Cell 介面 (SS 模型)，支援 .xls/.xlsx 切換。
• 建立樣式工廠類，集中管理樣式複用。
• 大量資料寫入時啟用 SXSSFWorkbook (串流模式) 避免 OOM。

若仍無法解決，請提供完整可重現的最小程式碼、POI 版本、Excel 版本與錯誤堆疊，方便進一步診斷。