PHP 輸出 Excel 下載時,若輸出前有任何空白、BOM、echo/log、錯誤訊息,或 Header 設定不當(Content-Type、Content-Disposition、編碼),瀏覽器下載的檔案會損壞、提示「格式錯誤」或「檔案損毀」。本文給出標準 Header 組合、輸出前緩衝控制、副檔名對應表與除錯清單。
<?php
$filePath = '/path/to/real/file.xlsx';
$fileName = 'export_' . date('Ymd_His') . '.xlsx';
if (!is_file($filePath)) {
http_response_code(404);
exit('檔案不存在');
}
// 1. 關閉輸出緩衝,防止前面有空白/BOM/錯誤輸出
while (ob_get_level()) ob_end_clean();
// 2. 核心 Header
header('Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'); // .xlsx
// header('Content-Type: application/vnd.ms-excel'); // .xls (舊版)
header('Content-Disposition: attachment; filename="' . rawurlencode($fileName) . '"');
header('Content-Transfer-Encoding: binary');
header('Content-Length: ' . filesize($filePath));
header('Cache-Control: must-revalidate, post-check=0, pre-check=0');
header('Pragma: public');
header('Expires: 0');
// 3. 直接輸出檔案流(不載入記憶體)
readfile($filePath);
exit;
| 副檔名 | Content-Type |
|---|---|
| .xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
| .xls | application/vnd.ms-excel |
| .csv | text/csv; charset=UTF-8 |
| .ods | application/vnd.oasis.opendocument.spreadsheet |
前有空白行、UTF-8 BOM、include 檔案末尾換行、var_dump/echo 除錯碼、Notice/Warning 錯誤訊息。ob_end_clean()、關閉 display_errors、檔案純 PHP 省略結尾 ?>。application/vnd.ms-excel,Excel 2007+ 會嘗試用舊版解析器導致失敗。Xlsx 存 .xlsx,Xls 存 .xls,Csv 存 .csv)。<?php
// 適用 PhpSpreadsheet 直接串流寫入瀏覽器
$spreadsheet = new \PhpOffice\PhpSpreadsheet\Spreadsheet();
// ... 填充資料 ...
$writer = \PhpOffice\PhpSpreadsheet\IOFactory::createWriter($spreadsheet, 'Xlsx');
header('Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
header('Content-Disposition: attachment; filename="stream_export.xlsx"');
header('Cache-Control: max-age=0');
$writer->save('php://output');
exit;
# 1. 瀏覽器開發者工具 Network 面板檢查:
# - Response Headers 是否含正確 Content-Type、Content-Length
# - Response Body 前幾位元組:PK\x03\x04 (ZIP/XLSX) 或 \xD0\xCF\x11\xE0 (OLE/XLS)
# 2. 命令列驗證:
curl -I "https://example.com/export.php"
# 應看到 Content-Type、Content-Disposition、Content-Length
# 3. 檢查 PHP 錯誤日誌:
tail -f /var/log/php-fpm/error.log