ThinkPHP验证码原理详解:从生成到验证的最佳实践-ThinkPHP-PHP中文网

thinkphp验证码本质是“图像+会话”协同机制：后端生成带随机字符的图片并存入当前用户session，前端提交后比对输入值与session中原始值；必须安装topthink/think-captcha扩展并启用session中间件，否则create()返回空白、check()恒为false。

thinkphp验证码原理详解:从生成到验证的最佳实践

ThinkPHP验证码本质是“图像+会话”的协同机制：后端生成一张带随机字符的图片，同时把这串字符原样存进当前用户的 Session；前端展示图片并收集用户输入，提交后比对输入值与 Session 中存储的原始值是否一致。整个流程依赖 Session 的稳定性和生命周期一致性，不是单纯调用两个方法就能跑通。

必须安装扩展并确保 Session 正常工作

从 ThinkPHP 5.1 起，验证码不再是内置功能，必须通过 Composer 安装 topthink/think-captcha。仅执行 composer require topthink/think-captcha 不够，还需确认 Session 已被中间件正确启用：

TP6 默认在 app/middleware.php 中注释了 \think\middleware\SessionInit::class，需手动取消注释
不能在控制器里写 session_start() —— 这无效，Session 必须由中间件自动初始化
快速验证 Session 是否就绪：在任意控制器方法中写 session('test', 'ok'); var_dump(session('test'));，输出 string(2) "ok" 才算正常

生成验证码要避开输出干扰，推荐模板函数

直接在控制器里 new Captcha()->create() 并 return，极易因布局模板中的空格、换行或提前 echo 导致图像流损坏（浏览器显示“无法加载图像”）。稳妥做法是交给框架自动处理：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

前端模板中直接使用 {:captcha_img()}，它会自动生成带时间戳参数的 <img src="/captcha?_=1748787620">，天然防缓存
若需自定义路由，应在路由文件中明确绑定：Route::get('captcha', [\think\captcha\facade\Captcha::class, 'create']);
该路由对应的方法体内不能有任何输出，包括 echo、var_dump、甚至末尾多一个空行

验证失败多数不是代码错，而是环境或时机问题

(new Captcha())->check($input) 返回 false，90% 情况与逻辑无关，重点排查以下三点：

用户输入为空或全空格 —— 建议前端提交前 .trim()，后端也做一次 trim($input)
Session ID 不一致 —— 登录页和提交页跨子域名（如 login.example.com vs www.example.com）或未统一 Cookie 域名配置，导致两次请求用了不同 Session
验证码已被消耗 —— ThinkPHP 默认一次有效，check() 成功后立即清除 Session 中的值；JS 重复提交、F5 刷新后重试旧值都会失败
大小写不匹配 —— 默认校验区分大小写，若前端输入小写而图片显示大写，需统一转大写再比对，或配置 'useZh' => false, 'codeSet' => 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789' 控制字符集