解決 Nginx + PHP-FPM 環境下 flush() 失效：緩衝區與 gzip 完整調教指南

現象

在 Nginx + PHP-FPM 架構下，呼叫 ob_flush() 和 flush() 仍無法即時輸出內容，瀏覽器需等待腳本結束才一次性顯示。phpinfo() 顯示 output_buffering 等設定正常，問題多半在 Nginx 層。

根因分析

1. FastCGI 緩衝：Nginx 預設 fastcgi_buffer_size 128k; fastcgi_buffers 8 128k;，PHP 輸出需累積 128 KB 才會傳給客戶端。
2. gzip 壓縮：Nginx 預設開啟 gzip，壓縮需等待足夠資料才開始，進一步延遲輸出。

解決步驟

1. 調整 Nginx FastCGI 緩衝區（建議 4k）

location ~ \.php$ {
    fastcgi_buffer_size 4k;
    fastcgi_buffers 8 4k;
    # 其他 fastcgi_param 設定...
}

2. 關閉該路由的 gzip

location /stream/ {
    gzip off;
    # 或僅針對特定 location 關閉
}

3. PHP 端輸出「填滿緩衝區」的初始資料

<?php
// 在 ob_flush()/flush() 前，先輸出 ≥ 4k 內容
echo str_repeat(' ', 1024 * 4); // 4 KB 空白

// 之後即可正常逐行輸出
for ($i = 1; $i <= 10; $i++) {
    echo "Line $i
";
    ob_flush();
    flush();
    sleep(1);
}
?>

完整 Nginx 範例配置

server {
    listen 80;
    server_name example.com;

    location /stream/ {
        gzip off;
        fastcgi_buffer_size 4k;
        fastcgi_buffers 8 4k;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
        include fastcgi_params;
    }
}

驗證方式

瀏覽器開啟開發者工具 Network 標籤，觀察 Content-Length 是否為 chunked，以及回應是否隨時間逐段出現。

常見誤區

• 只調 PHP output_buffering = Off 不調 Nginx → 無效。
• 只調小 FastCGI buffer 不關 gzip → 仍可能延遲。
• 忘記先輸出填充資料 → 首次 flush 仍被 Nginx 擋住。

總結

「Nginx 緩衝區調小 + 關 gzip + PHP 先填充」三步缺一不可。調整後，PHP 的 ob_flush()/flush() 即可在長輪詢、SSE、即時日誌等場景正常運作。