PHP 文件下載響應頭最佳實踐：四行代碼搞定標準輸出

文件下載功能看似簡單，但響應頭設置不當會導致文件名亂碼、瀏覽器直接預覽而非下載、大文件傳輸中斷等問題。本文給出生產級的標準頭部配置，並解析每個頭部的作用與避坑點。

標準下載響應頭（生產環境可直接用）

// $file 為服務器絕對路徑
header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="' . basename($file) . '"');
header('Content-Length: ' . filesize($file));
readfile($file);  // 直接輸出文件流，內存友好

每個頭部深度解析

進階：中文文件名完美兼容方案

$filename = basename($file);
$encoded = urlencode($filename);
$encoded = str_replace('+', '%20', $encoded);  // 修正空格編碼

// 現代瀏覽器支援 RFC 5987
header("Content-Disposition: attachment; filename*=UTF-8''{$encoded}; filename=\"{$filename}\"");
// 兼容舊版 IE（<9）可加判斷 User-Agent 降級

大文件傳輸優化建議

1. 啟用 X-Sendfile / X-Accel-Redirect：將文件傳輸交給 Nginx/Apache，PHP 僅驗證權限並發送頭部，極大降低 PHP 進程佔用

   // Nginx 配置需 location /protected/ { internal; alias /data/files/; }
   header('X-Accel-Redirect: /protected/' . basename($file));
   header('Content-Disposition: attachment; filename="..."');
   exit;

2. 分塊讀取 + 緩衝刷新（無 X-Sendfile 權限時）：

   $fp = fopen($file, 'rb');
   while (!feof($fp)) {
       echo fread($fp, 8192);
       ob_flush(); flush();
   }
   fclose($fp);

3. 設置合理的執行時間與內存限制：

   set_time_limit(0);
   ini_set('memory_limit', '64M');

常見坑點速查表

• ❌ header('Content-Type: application/pdf') 導致瀏覽器直接打開而非下載
• ❌ 文件名含空格/中文未加雙引號或編碼，導致下載文件名截斷/亂碼
• ❌ 缺少 Content-Length，下載進度條卡在 0% 或無法斷點續傳
• ❌ 使用 file_get_contents 讀取大文件導致內存溢出
• ❌ 輸出前有 BOM、空白、echo 等輸出，破壞二進制流

掌握這套標準頭部組合與優化手段，即可應對從 KB 到 GB 級別的各類文件下載場景，兼容性與性能雙保障。