ThinkPHP 8 验证码需严格完成五步：安装扩展、启用 GD/Openssl、开启 Session 中间件、配置 captcha.php、调用 captcha_img() 与 captcha_check()；缺一即导致图片空白或校验失败。
验证码生成必须走五步，缺一就失败
ThinkPHP 8 不再内置验证码功能，必须手动完成五个环节：安装扩展、启用 GD 和 OpenSSL、开启 Session 中间件、配置 captcha.php、调用 captcha_img() 与 captcha_check()。任意一步遗漏，都会出现图片空白或校验始终返回 false。
- 安装扩展：执行
composer require topthink/think-captcha，确认vendor/topthink/think-captcha目录存在 - 检查 PHP 扩展：确保
php.ini中已启用extension=gd和extension=openssl，重启 Web 服务 - 启用 Session：打开
app/middleware.php，确认\think\middleware\SessionInit::class在 middleware 数组中且未被注释 - 快速验证 Session：在控制器中写
session('test', 'ok'); var_dump(session('test'));，输出"ok"即生效 - 模板中直接使用：
{:captcha_img()}会自动渲染带时间戳的 img 标签，支持点击刷新
表单提交时的验证码校验要点
用户输入的验证码值需严格清洗并比对，不能跳过 trim 或忽略大小写逻辑。推荐统一转小写处理，避免因输入习惯导致误判。
- 获取输入值：用
$input = trim($this->request->post('captcha'))，不建议用input('post.captcha')（旧写法兼容性弱） - 执行校验：直接调用
captcha_check($input)，它内部已自动读取 session 中存储的原始码并比对 - 失败响应：返回标准 JSON，如
return json(['code'=>0, 'msg'=>'验证码错误']) - 注意字段名：表单中 input 的 name 必须为
captcha（默认键），否则captcha_check()找不到对应 session 值
进阶配置：按需调整验证码行为
所有参数集中在 config/captcha.php，无需改源码。常用调整项包括长度、字体、干扰、过期时间等，多应用项目可为每个应用单独配一份该文件。
- 基础配置示例：
'length' => 4（4位字符）、'fontSize' => 28、'useNoise' => false（去杂点更清晰） - 中文验证码：设
'useZh' => true，并确保项目中存在simhei.ttf字体文件（路径需正确，如public/fonts/simhei.ttf） - 算术验证码：启用
'math' => true，显示类似 “5+3=” 的题目，提升防机器能力 - 有效期控制：修改
'expire' => 300（单位秒），超时后自动失效，无需手动清理
避免踩坑的三个实操提醒
很多问题不是代码写错，而是环境或调用方式不对。以下三点高频出错，务必核对。
立即学习“PHP免费学习笔记（深入）”；
- 不要在控制器里手动 new Captcha() 后直接 return 图片内容——容易因空格、BOM 或响应头冲突导致图像损坏；坚持用
{:captcha_img()}或captcha_src() - 不要在表单验证器中混用
'captcha'规则和captcha_check()双重校验——二者原理不同，captcha规则是基于 session 的封装，而captcha_check()是底层函数，选其一即可 - API 模式下（如前后端分离）需切换策略：关闭默认图片路由，改用
Captcha::create()生成含img和code的数组，将code存入 cache（带 key），前端提交时附带该 key 供后端查缓存比对
