ThinkPHP5验证码需环境、配置、调用三者协同：GD和Session必须启用并验证；安装须匹配TP版本（5.0用v1.，5.1+用v2.）；模板用{:captcha_img()}嵌入，前端刷新加随机数防缓存；校验前trim输入，统一用captcha_check()，成功即失效。
ThinkPHP5验证码不是装完扩展就能用的，关键在环境、配置、调用三者严丝合缝。GD没开、Session没启、参数写错或校验方式不匹配，任一环节出问题都会导致“图片空白”“总提示错误”“点一下就失效”。下面按真实开发顺序讲清核心要点。
确保基础环境就绪
验证码依赖图像生成与会话存储，这两项必须提前验证到位：
-
GD扩展必须启用：运行
php -m | grep gd，有输出即开启；若无，修改php.ini取消extension=gd前的分号，重启Web服务 -
Session中间件必须启用：打开
app/middleware.php，确认\think\middleware\SessionInit::class已取消注释 -
快速验证Session是否生效：在任意控制器中写
session('test', 'ok'); var_dump(session('test'));，输出string(2) "ok"才算通过 -
别手动调用
session_start()：ThinkPHP的Session必须由中间件统一管理，混用会导致$_SESSION与框架session()不同步
安装与版本必须严格匹配
装错版本是新手最常踩的坑，直接报类不存在或方法签名错误：
-
TP5.0项目：执行
composer require topthink/think-captcha=1.* -
TP5.1及以上（含5.1.40等小版本）：执行
composer require topthink/think-captcha=2.* -
国内网络慢？先切镜像：
composer config -g repo.packagist composer https://packagist.phpcomposer.com -
装完务必检查：
vendor/topthink/think-captcha目录存在，且config/captcha.php已生成（若无可手动创建）
模板嵌入与前端刷新要规范
验证码图像是二进制流，任何额外输出（空格、换行、echo）都会破坏结构，导致“损坏的图像”：
立即学习“PHP免费学习笔记（深入）”；
-
推荐写法：模板中直接用
{:captcha_img()}，它自动生成带防缓存时间戳的<img src="/captcha?_=xxx"> -
点击刷新：加
onclick="this.src='{:captcha_src()}?'+Math.random()"，避免浏览器缓存旧图 -
跨子域/协议需一致：登录页是
login.example.com，提交页是www.example.com，Session ID不一致会导致校验必失败 -
勿手拼URL：不要写
/captcha.html或/index.php/captcha，除非你已配好对应路由和重写规则
后端校验逻辑必须一次到位
验证码本质是一次性口令，校验失败多因输入未清理、Session失效或已消耗，而非比对逻辑本身：
-
接收输入先去空格：
$code = trim(input('post.code'));，用户多敲一个空格就失败 -
校验用标准方式：
if (!captcha_check($code)) { $this->error('验证码错误'); }，无需手动读Session -
大小写敏感默认开启：若前端转小写，后端配置中需设
'useZh' => false并确认codeSet不含大小写混淆字符 -
成功即失效：
captcha_check()返回true后，系统自动清除Session中的值；重复提交或刷新页面重试旧值必然失败
