thinkphp 8 验证码需五步全到位：安装think-captcha扩展、启用gd和openssl、启用session中间件、配置captcha.php、调用captcha_img()与captcha_check()；缺一即导致图像空白或校验恒false。
ThinkPHP 8 的验证码不是默认内置功能，必须手动安装扩展、启用基础服务、配置参数、生成图像、校验输入，五步缺一不可。否则你会遇到 captcha_img() 显示空白、captcha_check() 恒返回 false 这类典型问题。
安装 think-captcha 扩展
TP8 不再自带验证码，需用 Composer 安装官方扩展：
- 打开终端，进入项目根目录（含
composer.json） - 执行命令：
composer require topthink/think-captcha - 安装完成后，检查
vendor/topthink/think-captcha目录是否存在 - 若报错“Class not found”，大概率是未启用
openssl或gd扩展——需编辑php.ini，取消注释extension=openssl和extension=gd，然后重启 PHP 服务
启用 Session 并确认生效
验证码依赖 Session 存储原始值，不启用就无法校验：
- 打开
app/middleware.php，确保\think\middleware\SessionInit::class在middleware数组中且未被注释 - 不要在控制器里手动调用
session_start()，它无效；必须靠中间件自动初始化 - 快速验证：在任意控制器方法中写
session('test', 'ok'); var_dump(session('test'));，输出string(2) "ok"即表示 Session 正常
生成并显示验证码图像
推荐使用框架封装好的函数，避免手动输出导致图片损坏：
- 在模板（如
login.html）中直接写：{:captcha_img()}，它会自动生成带时间戳的<img src="/captcha?_=1748935020"> - 如需点击刷新，可加简单 JS：
<img src="%7B:captcha_src()%7D" onclick="this.src='{:captcha_src()}'+Math.random()"> - 不建议在控制器里写
new Captcha()->create()后直接 return，容易因空格、换行或响应头冲突导致图像无法加载
后端校验用户输入
提交表单时，用 captcha_check() 判断是否匹配：
- 获取用户提交的验证码值（注意 trim 去空格）：
$input = trim($this->request->post('captcha')); - 执行校验：
if (!captcha_check($input)) { return json(['code'=>0, 'msg'=>'验证码错误']); } - 常见失败原因：前后端请求 session_id 不一致（跨子域/跨协议）、验证码已使用过（默认一次有效）、大小写不一致（配置中可设
'useZh'=>false, 'codeSet'=>'0123456789'控制字符集）
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
