ThinkPHP8需手动引入topthink/think-captcha扩展并启用GD、OpenSSL扩展，配置Session中间件确保正常工作，模板中用{:captcha_img()}显示验证码，后端用captcha_check()验证且需trim()和注意大小写。
ThinkPHP8 本身不带验证码功能，必须手动引入 topthink/think-captcha 扩展，并确保 Session 正常工作，否则图片空白、校验永远失败。整个流程不复杂但容易忽略关键环节。
一、安装扩展并启用必要扩展
打开终端，进入项目根目录（含 composer.json），执行：
composer require topthink/think-captcha
安装完成后检查：vendor/topthink/think-captcha 目录是否存在。接着运行命令生成配置文件：
立即学习“PHP免费学习笔记（深入）”；
php think captcha:install
该命令会在 config/ 下生成 captcha.php，并在 public/static/captcha/ 放入前端资源。
同时确认 PHP 环境已开启两个基础扩展：
-
GD 库：编辑
php.ini，取消注释extension=gd，重启 Web 服务（如php think run） -
OpenSSL：同样在
php.ini中启用extension=openssl
二、开启 Session 中间件
验证码值靠 Session 存储，若未初始化 Session，captcha_check() 必然返回 false。
打开 app/middleware.php，确保以下中间件已取消注释：
\think\middleware\SessionInit::class
验证是否生效：在任意控制器方法中写
session('test', 'ok'); var_dump(session('test'));
输出 string(2) "ok" 即表示 Session 已正常工作[^1]。
三、在页面显示验证码图片
推荐直接在模板（如 login.html）中使用内置函数：
{:captcha_img()}
它会自动渲染为带时间戳的 <img src="/captcha?_=1717542390"> 标签，避免缓存问题。
如需点击刷新，可加简单 JS：
<img src="{:captcha_src()}" onclick="this.src='{:captcha_src()}'+Math.random()">
注意：不要在控制器里用 new Captcha()->create() 直接 return 图片内容，易因输出顺序或空格导致图像损坏[^2]。
四、后端接收并验证用户输入
假设表单提交字段名为 captcha，在登录/注册控制器中这样验证：
$input = trim(input('post.captcha'));<br>if (empty($input) || !captcha_check($input)) {<br> return json(['code'=>0, 'msg'=>'验证码错误']);<br>}
常见失败原因：
- 用户输入前后有空格 → 一定要先
trim() - 大小写不一致 → 默认区分大小写，可统一转大写：
captcha_check(strtoupper($input)) - Session ID 不一致 → 检查是否跨子域名、是否禁用了 Cookie、是否用了不同协议（http/https）
- 验证码已被使用 → ThinkPHP 默认一次有效，check 成功后自动清除，不可重复提交旧值
不复杂但容易忽略。
