ThinkPHP验证码登录教程

ThinkPHP 验证码登录总翻车？别急着怀疑代码，十有八九是环境或调用链断了——需要 Composer 安装 think-captcha，确保 GD 和 OpenSSL 扩展已启用并重启服务；Session 中间件得手动开启；跨域请求得统一域名；输出验证码图像时保持干净，推荐直接上 captcha_img()；至于 check() 失败，多半是没做 trim、大小写没对齐或者验证码已经一次性的消耗掉了。

验证码登录在 ThinkPHP 里不是装上去就能跑的功能——captcha_check() 永远返回 false、图像空白、点刷新没反应……这些坑，90% 都不是代码逻辑写错了，而是环境配置或者调用链路在某个环节断了。

安装 think-captcha 并确认 GD 和 OpenSSL 已启用

扩展必须通过 Composer 安装，而且它依赖两个 PHP 扩展：GD（用来绘图）和 OpenSSL（部分版本校验逻辑需要）。缺一个都不行，否则 Captcha::create() 会直接返回空或者报错。

• 先执行 composer require topthink/think-captcha，装完检查一下 vendor/topthink/think-captcha 目录是不是真的存在——别跑完命令就不管了。
• 然后打开 php.ini，找到 extension=gd 和 extension=openssl，确保它们前面没有分号注释，改完之后必须重启 Web 服务（不管你是 php think run 还是 Apache/Nginx）。
• 怎么验证 GD 真的生效了？简单：在控制器里写一行 var_dump(extension_loaded('gd'));，输出 bool(true) 才算过关。

Session 中间件必须显式启用（TP6/TP8 默认关闭）

验证码的值存在 $_SESSION 里，但 ThinkPHP 6+ 默认不会自动启动 Session。就算你手动调 session_start() 也没用——框架会直接忽略它。

• 打开 app/middleware.php，找到 thinkmiddlewareSessionInit::class 这一行。
• 把行首的 // 删掉，让它变成活动项。
• 怎么确认真生效了？随便在某个控制器方法里写 session('test', 'ok'); var_dump(session('test'));，输出 string(2) "ok" 才算成功。
• 特别注意：如果前后端跨域（比如前端跑在 http://localhost:5173，后端跑在 http://127.0.0.1:8000），Session ID 不一致，check() 铁定失败——没有例外。

生成验证码时别直接 return create()，优先用 captcha_img() 或路由绑定

Captcha::create() 返回的是二进制图像流。如果你的控制器方法里还有其他输出——哪怕模板里多了一个空格、一个 echo 或者 var_dump——这张图就坏了，浏览器会告诉你“无法加载图片”。

• 最省心的方式：在模板里直接写 {:captcha_img()}，它会自动生成带时间戳的 ，什么都不用操心。
• 如果你非要自定义路由，必须在 route/app.php 里严格绑定：Route::get('captcha', [thinkcaptchafacadeCaptcha::class, 'create']);，少写一个参数都可能跑偏。
• 自己写控制器方法的话，方法体里只能有一行：return thinkcaptchafacadeCaptcha::create();，前后不能有任何其他输出。
• 前端刷新验证码时记得带随机参数，推荐这么写：onclick="this.src='{:url('index/captcha')}?'+Math.random()"，否则浏览器缓存会让你怀疑人生。

check() 失败的三个真实原因和对应解法

captcha_check($input) 返回 false，几乎从来不是因为“逻辑写反了”，而是运行时的上下文出了问题。

• 用户输入没 trim：前端可能提交了 "abc "（带个空格），而 session 里存的是 "abc"。校验之前务必加一句 $input = trim($input)。
• 大小写不一致：默认配置下校验是区分大小写的。如果前端输入全小写，但验证码图里是大写字母，那就对不上。解决办法要么前端统一转大写，要么在 config/captcha.php 里加 'useZh' => false, 'useCurve' => true，同时确认 'codeSet' 里没有大小写混排。
• 验证码已被消耗：ThinkPHP 默认一张验证码只能用一次。check() 成功后 session 里的值会自动清空；如果 JS 重复提交，或者用户 F5 刷新后拿旧值重试，铁定失败。调试时建议每次请求都先刷新验证码。

还有一个最容易忽略的点：验证码配置文件 config/captcha.php 里的键名必须跟官方文档完全一致。比如你写成 'length' 没问题，但写成 'len' 就不行——框架会静默忽略非法键，仍然用默认值（通常是 4 位、1800 秒过期），而你还在纳闷为什么自己改了配置没效果。