您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 綜合知識

ThinkPHP 驗證碼無法顯示完美解決方案：ob_end_clean 與輸出緩衝區控制

編輯：PHP 綜合知識

前言

在 ThinkPHP 開發中，驗證碼（`Image::buildImageVerify()`）無法顯示、僅出現「小 X」或圖片損壞圖示，是開發者常遇到的棘手問題。官方文檔列舉了四大檢查項（GD庫、輸出前輸出、類庫載入、字體檔案），但實務上最常見卻最容易被忽略的原因是：驗證碼輸出前已有內容輸出（含 BOM、空白、echo、var_dump、錯誤訊息等），導致 HTTP 標頭已送出，圖片二進位資料被污染。本文提供徹底解決方案與原理解析。

核心問題：輸出緩衝區污染

PHP 輸出圖片時，必須確保：

發送正確的 `Content-Type: image/jpeg`（或 png/gif）標頭
標頭之後只能有圖片二進位資料，不能有任何文字、空白、HTML、BOM

若在呼叫 `Image::buildImageVerify()` 之前，任何地方（框架核心、配置檔、控制器建構子、模型、視圖、甚至 `php.ini` 設定的 `auto_prepend_file`）有輸出，瀏覽器會將其視為圖片資料一部分，導致圖片解析失敗。

解決方案：`ob_end_clean()` 徹底清除緩衝區

在驗證碼生成方法的最開頭呼叫 `ob_end_clean()`，丟棄所有已產生的輸出緩衝區內容，確保乾淨輸出。

<?php
namespace app\controller;

use think\Controller;
use think\Image;

class Auth extends Controller
{
    /**
     * 顯示驗證碼
     * 路由：GET /auth/captcha
     */
    public function captcha()
    {
        // 關鍵：清除所有先前的輸出緩衝區
        // ob_end_clean() 會關閉並丟棄「最內層」的緩衝區
        // 若有多層巢狀 ob_start()，需呼叫多次或用 ob_get_level() 迴圈
        while (ob_get_level() > 0) {
            ob_end_clean();
        }

        // 現在可以安全輸出圖片標頭與二進位資料
        Image::buildImageVerify([
            'length'   => 4,
            'fontSize' => 20,
            'width'    => 120,
            'height'   => 40,
            'useNoise' => true,
            'fontttf'  => 'path/to/your/font.ttf', // 確保字體檔案存在
        ]);
    }
}

為什麼單獨 `ob_end_clean()` 有時不夠？

多層緩衝區：框架啟動、中介軟、模板引擎可能各自呼叫 `ob_start()`，形成巢狀結構。單次 `ob_end_clean()` 僅清除最內層。
已發送標頭：若輸出量超過 `output_buffering` 設定（預設 4096 bytes），PHP 會自動刷新輸出並發送標頭，此時 `ob_end_clean()` 會失效並拋出警告。

進階防禦：封裝為可復用 Trait

<?php
namespace app\traits;

trait CaptchaHelper
{
    /**
     * 確保乾淨輸出環境並生成驗證碼
     * @param array $config Image::buildImageVerify 設定
     */
    protected function outputCaptcha(array $config = []): void
    {
        // 1. 清除所有輸出緩衝區
        while (ob_get_level() > 0) {
            ob_end_clean();
        }

        // 2. 發送正確標頭（Image 類別內部會發送，但可在此明確設定）
        header('Content-Type: image/jpeg');
        header('Cache-Control: no-store, no-cache, must-revalidate, max-age=0');
        header('Pragma: no-cache');
        header('Expires: Thu, 01 Jan 1970 00:00:00 GMT');

        // 3. 生成驗證碼
        \think\Image::buildImageVerify($config);
        exit; // 確保無後續輸出
    }
}

// 控制器使用
namespace app\controller;
use think\Controller;
use app\traits\CaptchaHelper;

class Auth extends Controller
{
    use CaptchaHelper;

    public function captcha()
    {
        $this->outputCaptcha([
            'length' => 4,
            'width'  => 130,
            'height' => 50,
        ]);
    }
}

官方四大檢查項補充說明

檢查項	實際排查步驟
① GD 庫支援	`php -m \| grep gd` 或 `phpinfo()` 確認 `GD Support => enabled`、`FreeType Support => enabled`、`JPEG/PNG Support => enabled`
② 輸出前無輸出	檢查所有 `.php` 檔案無 BOM（用編輯器存為 UTF-8 無 BOM）、無結尾 `?>` 後的空白行、無 `echo`/`var_dump`/`print_r`、無錯誤/警告輸出（設定 `display_errors=Off` 生產環境）
③ Image 類庫載入	ThinkPHP 5/6 通常自動載入，若手動 `require` 確認路徑正確；命名空間 `use think\Image;`
④ 中文驗證碼字體	中文驗證碼需 TTF 字體檔，確認 `fontttf` 參數路徑正確、檔案可讀、字體支援所需字元

除錯技巧：如何確認輸出被污染

瀏覽器開發者工具 → Network → 點選驗證碼請求 → Response 標籤，若看到 HTML/文字/空白混雜在二進位資料前，即確認被污染。
在驗證碼方法第一行加入 `file_put_contents('/tmp/debug_ob.log', 'level='.ob_get_level().' content='.ob_get_contents());` 檢查緩衝區狀態。
臨時在 `index.php` 最頂端加入 `ob_start();`，在驗證碼方法前加入 `ob_end_clean();`，若解決問題，說明污染源在框架啟動流程中。

ThinkPHP 6/8 專屬注意事項

中介軟可能輸出內容（如日誌中介軟 `echo`），請檢查 `app/middleware.php` 註冊的中介軟。
異常處理器 `app/ExceptionHandle.php` 若在 `render()` 中輸出 HTML，會污染驗證碼。驗證碼路由建議排除全域中介軟或獨立路由群組。
路由定義：`Route::get('captcha', 'Auth/captcha')->middleware([]);` 禁用中介軟。

替代方案：驗證碼服務化（API 模式）

將驗證碼生成獨立為無狀態 API 服務（如 `/api/captcha`），前端 `` 請求，後端純輸出圖片，**不載入框架完整啟動流程**甚至使用獨立微框架（Slim、Lumen）或純 PHP 腳本，徹底避免框架層級的輸出干擾。

結語

ThinkPHP 驗證碼無法顯示，**90% 以上案例源於輸出緩衝區污染**。徹底解決之道：在驗證碼生成入口**最優先**呼叫 `while (ob_get_level()) ob_end_clean();` 確保乾淨環境，並配合 `exit` 結束腳本。搭配官方四大檢查項（GD、BOM、類庫、字體），即可永久根除「小 X」問題。建議將此邏輯封裝為 Trait 或基底控制器方法，專案統一複用，避免重複踩坑。