ThinkPHP 驗證碼無法顯示的完整解決方案

在使用 ThinkPHP 開發項目時，驗證碼無法顯示是常見問題。這通常由 GD 庫未啟用、代碼實現錯誤或路徑配置問題引起。本文提供系統性的排查與解決步驟，幫助你快速恢復驗證碼功能。

一、檢查 PHP 環境：確保 GD 庫已啟用

驗證碼生成依賴 GD 庫。打開 php.ini，搜尋 extension=php_gd2.dll（Windows）或 extension=gd（Linux/Mac），確保前面的分號 ; 已移除。修改後重啟 Web 服務器（Apache/Nginx/PHP-FPM）。

驗證方法：建立 phpinfo.php，檢查 GD 區塊是否顯示 GD Support: enabled。

二、控制器中正確實現驗證碼生成方法

在對應的控制器類中新增 verify 方法：

<?php
public function verify() {
    // ThinkPHP 3.x 寫法
    import('ORG.Util.Image');
    Image::buildImageVerify();
    
    // ThinkPHP 5.x/6.x 建議使用內置驗證碼類
    // use think\captcha\Captcha;
    // $captcha = new Captcha();
    // $captcha->entry();
}

三、前端表單正確引用驗證碼圖片

在表單模板中：

<input type="text" name="verify" placeholder="請輸入驗證碼" />
<img id="verifyImg" src="__URL__/verify" onclick="changeVerify()" title="點擊刷新驗證碼" style="cursor:pointer;vertical-align:middle;" />

關鍵點： src 指向控制器的 verify 方法；onclick 綁定刷新函數。

四、JavaScript 實現點擊刷新驗證碼

<script>
function changeVerify() {
    var timenow = new Date().getTime();
    document.getElementById('verifyImg').src = '__URL__/verify/' + timenow;
}
</script>

加入時間戳參數可有效防止瀏覽器緩存導致圖片不更新。

五、後端驗證邏輯正確判斷用戶輸入

<?php
// 表單提交處理方法中
if (session('verify') != md5($_POST['verify'])) {
    $this->error('驗證碼錯誤！');
}
// 驗證通過後繼續業務邏輯

注意： ThinkPHP 3.x 使用 $_SESSION['verify']，5.x/6.x 建議用 session('verify')；驗證碼存儲時已經過 MD5 加密，驗證時需同樣處理。

六、常見問題排查清單

• ✅ GD 庫已啟用且支援 FreeType、JPEG、PNG
• ✅ 驗證碼生成方法輸出無多餘空白字符（檢查 <?php 前無空行）
• ✅ Session 正常啟動（session_start() 或框架自動處理）
• ✅ 路由/URL 模式下 __URL__ 正確解析為當前控制器地址
• ✅ 驗證碼字體文件存在且可讀（ThinkPHP 預設字體路徑）

七、ThinkPHP 5.x/6.x 現代化寫法建議

新版框架內置 think-captcha 擴展包，安裝後配置更簡單：

// 安裝
composer require topthink/think-captcha

// 控制器
public function verify() {
    return captcha_img();
}

// 驗證
if (!captcha_check($_POST['verify'])) {
    $this->error('驗證碼錯誤');
}

此方式自動處理 Session、字體、干擾線等細節，減少出錯機率。

通過以上步驟，絕大多數 ThinkPHP 驗證碼顯示異常問題均可解決。若問題持續，建議檢查服務器錯誤日誌（Apache error.log 或 PHP-FPM 日誌）獲取詳細報錯信息。