ThinkPHP验证码需手动安装扩展、启用Session、配置参数并校验，缺一不可；90%问题源于环境配置错误而非代码逻辑。
ThinkPHP 验证码不是内置功能，必须手动安装扩展、启用 Session、配置参数、生成图像并校验——缺一不可。新手常卡在“图片不显示”或“始终验证失败”，问题90%出在环境配置而非代码逻辑。
安装对应版本的 think-captcha 扩展
不同 ThinkPHP 版本需匹配特定扩展包，装错版本会直接报错 Class not found：
- ThinkPHP 5.0：执行 composer require topthink/think-captcha=1.*
- ThinkPHP 5.1 及以上（含 6.x、8.x）：执行 composer require topthink/think-captcha
安装完成后，检查 vendor/topthink/think-captcha/src/Captcha.php 是否存在。再在控制器中临时加一行：
dump(class_exists('think\captcha\Captcha')); —— 输出 true 才算成功加载。
必须启用 Session 中间件
验证码值靠 Session 存储，未启用中间件会导致 create() 返回空白、check() 恒为 false：
立即学习“PHP免费学习笔记（深入）”；
- 打开 app/middleware.php
- 找到 hinkmiddlewareSessionInit::class
- 删掉该行开头的 // 注释符号，确保它被启用
验证是否生效：在任意控制器方法中写 session('test', 'ok'); var_dump(session('test'));，输出 string(2) "ok" 即表示 Session 已正常工作。
配置与生成验证码图像
推荐两种方式，新手建议优先用第一种，更少出错：
- 模板中直接调用 {:captcha_img()} —— 自动输出带随机参数的 img 标签，点击可刷新，无需额外路由或控制器方法
- 若需自定义，新建控制器方法（如 Index::captcha），内容只写：
return hinkcaptcha acadeCaptcha::create();
并在模板中使用：
<img src="{:url('index/captcha')}" onclick="this.src='{:url('index/captcha')}?'+Math.random()">
注意：该方法体内不能有任何 echo/print/dump/空格/换行，否则图像流会被破坏，浏览器显示“无法加载”。
后端验证用户输入
校验必须在接收 POST 请求的控制器动作中进行，且要处理常见干扰项：
- 前端提交前先 trim() 去除首尾空格：$input = trim($this->request->post('captcha'));
- 调用校验：if (!captcha_check($input)) { // 验证失败 };
- 默认区分大小写，若前端输入小写而验证码是大写，可统一转大写：captcha_check(strtoupper($input))
- 验证码一次有效，check() 成功后自动清除，勿重复提交旧值
若仍返回 false，请检查：前后端是否同域（跨子域名会导致 session_id 不一致）、GD 扩展是否启用（phpinfo() 查看 gd 模块）、php.ini 中 extension=gd 是否已开启并重启服务。
