萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 下載 Excel 檔案無法開啟?完整 Header 設定與常見坑點排查

PHP 輸出 Excel 下載時,若輸出前有任何空白、BOM、echo/log、錯誤訊息,或 Header 設定不當(Content-Type、Content-Disposition、編碼),瀏覽器下載的檔案會損壞、提示「格式錯誤」或「檔案損毀」。本文給出標準 Header 組合、輸出前緩衝控制、副檔名對應表與除錯清單。

標準下載 Header 組合(適用 .xls / .xlsx)

<?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 對照表

副檔名Content-Type
.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xlsapplication/vnd.ms-excel
.csvtext/csv; charset=UTF-8
.odsapplication/vnd.oasis.opendocument.spreadsheet

三大常見導致檔案損壞的原因

  1. 輸出前有內容: 前有空白行、UTF-8 BOM、include 檔案末尾換行、var_dump/echo 除錯碼、Notice/Warning 錯誤訊息。
    → 解決:ob_end_clean()、關閉 display_errors、檔案純 PHP 省略結尾 ?>。
  2. Content-Type 不匹配:.xlsx 卻送 application/vnd.ms-excel,Excel 2007+ 會嘗試用舊版解析器導致失敗。
    → 解決:嚴格對應上表。
  3. 檔案實際格式與副檔名不符:用 PHPExcel 產出 .xlsx 卻存成 .xls,或 CSV 存成 .xlsx。
    → 解決:Writer 類別與副檔名一致(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
copyright © 萬盛學電腦網 all rights reserved