PHP 輸出緩衝區控制完全指南：ob_* 函數、flush 機制與實戰模式

PHP 輸出緩衝區控制完全指南：ob_* 函數、flush 機制與實戰模式

PHP 輸出緩衝 是理解 echo 何時真正發送到瀏覽器、實現長輪詢/流式響應、捕獲輸出內容、壓縮輸出的核心機制。本文系統梳理 output_buffering 配置、ob_* 函數族、flush() 與 Web 服務器/瀏覽器緩衝的交互，並給出生產級實戰模式。

緩衝層級架構

PHP 腳本
    │
    ▼
PHP 內部輸出緩衝 (output_buffering / ob_start)
    │  可巢狀多層 (ob_get_level())
    ▼
PHP 輸出到 SAPI (PHP-FPM/Apache/CLI)
    │
    ▼
Web 服務器緩衝 (Nginx fastcgi_buffering / Apache mod_deflate)
    │
    ▼
網絡傳輸 (TCP 滑動窗口)
    │
    ▼
瀏覽器緩衝 (渲染引擎決定何時繪制)
    │
    ▼
用戶看到內容

核心配置：output_buffering

; php.ini
output_buffering = 4096  ; 默認 4KB 內部緩衝
; output_buffering = Off ; 關閉 (僅 CLI 建議)
; output_buffering = 0   ; 同 Off

• 啟用時，所有 echo/print 先寫入 PHP 內部緩衝區，達到 4KB 或腳本結束才刷新到 SAPI。
• ob_start() 會在當前層級之上創建新緩衝層，output_buffering 視為底層隱式層。
• CLI 模式默認 output_buffering = 0 (無緩衝)。

ob_* 函數族速查表

關鍵區別：ob_flush() vs flush()

// 正確的流式輸出順序 (PHP 緩衝開啟時)
echo "data chunk 1";
ob_flush(); // 1. PHP 內部緩衝 → SAPI
flush();    // 2. SAPI → Web Server → TCP → 瀏覽器
sleep(1);

echo "data chunk 2";
ob_flush();
flush();
// ...

• ob_flush()：釋放 PHP 內部緩衝區到 SAPI 層。
• flush()：通知 SAPI/Web Server 將數據發送到客戶端。
• 必須成對使用：若 PHP 開啟緩衝，缺一不可；若 output_buffering=Off 且無 ob_start，只需 flush()。

實戰模式一：流式響應 / 長輪詢 / SSE

// 禁用所有緩衝 (生產環境建議在入口文件統一設置)
if (ob_get_level()) ob_end_clean();
ini_set('output_buffering', '0');
ini_set('zlib.output_compression', '0'); // 禁用壓縮
header('Content-Type: text/event-stream');
header('Cache-Control: no-cache');
header('X-Accel-Buffering: no'); // 禁用 Nginx fastcgi_buffering

$lastEventId = $_SERVER['HTTP_LAST_EVENT_ID'] ?? 0;

while (true) {
    // 檢查客戶端斷開
    if (connection_aborted()) break;

    $data = getNewEventsSince($lastEventId);
    if ($data) {
        echo "id: {$data['id']}\n";
        echo "data: " . json_encode($data['payload']) . "\n\n";
        $lastEventId = $data['id'];
        ob_flush();
        flush();
    }
    sleep(1); // 或 usleep(200000)
}

// 關鍵：Nginx 配置
// location /events {
//     proxy_buffering off;
//     proxy_cache off;
//     fastcgi_buffering off;
// }

實戰模式二：捕獲模板輸出 / 模板引擎核心

function render(string $template, array $data = []): string {
    extract($data);
    ob_start();
    include $template;
    return ob_get_clean();
}

// 使用
$html = render('user_profile.php', ['user' => $user, 'posts' => $posts]);
echo $html; // 或返回 API 響應

實戰模式三：輸出壓縮 (gzip/deflate)

// 自動壓縮 (推薦：Web 服務器層面處理)
// nginx: gzip on; gzip_types text/css application/json application/javascript;

// PHP 層面 (不推薦，性能差)
ob_start('ob_gzhandler');
// 或手動
ob_start(function($buffer) {
    if (strpos($_SERVER['HTTP_ACCEPT_ENCODING'], 'gzip') !== false) {
        return gzencode($buffer, 6);
    }
    return $buffer;
});

瀏覽器緩衝行為差異

常見問題排查清單

1. 輸出不生效：檢查 output_buffering、zlib.output_compression、Nginx fastcgi_buffering、gzip、CDN 緩存。
2. Headers already sent：ob_start() 必須在任何輸出 (含空白字符、BOM) 之前調用。
3. 內存耗盡：大數據流式輸出時勿用 ob_get_contents()，直接 echo + ob_flush() + flush()。
4. 壓縮導致流式失效：ob_gzhandler / zlib.output_compression 會緩衝整個響應體，禁用之。

精通輸出緩衡機制，是構建高性能流式 API、實時儀表板、大文件下載、模板引擎的基石技能。