Java 導出 CSV 檔案 response.getOutputStream() 空指針異常排查

Servlet/Controller 中導出 CSV 檔案時，response.getOutputStream() 拋出 NullPointerException。本文分析常見原因並提供標準導出範本。

核心原因：response 物件為 null 或已提交

標準 CSV 導出範本

@GetMapping("/export.csv")
public void exportCsv(HttpServletResponse response) throws IOException {
    // 1. 設置回應頭（必須在 getOutputStream() 之前）
    response.setContentType("text/csv; charset=UTF-8");
    response.setHeader("Content-Disposition", "attachment; filename=\"export_" + LocalDate.now() + ".csv\"");
    response.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
    response.setHeader("Pragma", "no-cache");
    response.setHeader("Expires", "0");
    // 防止中文檔名亂碼 (RFC 5987)
    String encodedFilename = URLEncoder.encode("導出_" + LocalDate.now() + ".csv", StandardCharsets.UTF_8)
        .replaceAll("\\+", "%20");
    response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + encodedFilename);

    // 2. 獲取輸出流
    try (ServletOutputStream out = response.getOutputStream();
         PrintWriter writer = new PrintWriter(new OutputStreamWriter(out, StandardCharsets.UTF_8))) {
        
        // 3. 寫入 BOM (UTF-8 with BOM) 讓 Excel 正確識別編碼
        out.write(new byte[]{(byte)0xEF, (byte)0xBB, (byte)0xBF});
        
        // 4. 寫入 CSV 內容
        writer.println("姓名,年齡,城市");
        writer.println("張三,25,北京");
        writer.println("李四,30,上海");
        // ... 從資料庫/服務查詢數據循環寫入
        
        writer.flush(); // 關鍵：確保緩衝區寫入 OutputStream
    }
    // try-with-resources 自動關閉流，提交回應
}

關鍵注意點

1. Header 先於 Stream：所有 setHeader/setContentType 必須在 getOutputStream() / getWriter() 之前完成。
2. 單一流原則：同一請求只能呼叫 其中一個**getOutputStream() 或 getWriter()，二擇一，否則 IllegalStateException。
3. 編碼一致性：OutputStreamWriter(..., UTF-8) 與 response.setCharacterEncoding("UTF-8") 保持一致。
4. 大數據流式寫入：避免一次性載入所有資料到記憶體，邊查詢邊 writer.println()。
5. 異常處理：若導出過程拋異常，回應可能已提交 Header，無法再傳錯誤頁，需在全域異常處理器記錄日誌。

@GetMapping("/export.csv")
public ResponseEntity<byte[]> exportCsv() {
    String csv = generateCsv(); // 產生 CSV 字串
    byte[] bytes = ("\uFEFF" + csv).getBytes(StandardCharsets.UTF_8); // 加 BOM
    
    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.parseMediaType("text/csv; charset=UTF-8"));
    headers.setContentDispositionFormData("attachment", "export_" + LocalDate.now() + ".csv");
    headers.setCacheControl("no-cache, no-store, must-revalidate");
    
    return new ResponseEntity<>(bytes, headers, HttpStatus.OK);
}