ThinkPHP8验证码需四步到位：准备PHP≥8.0并启用GD/OpnSSL扩展、Composer安装topthink/think-captcha、启用Session中间件、配置captcha.php；缺一则图片空白或校验失败。
ThinkPHP8 不是“装完就能用”的开箱框架，它需要明确环境准备、扩展安装、中间件启用和配置落地四个关键动作。验证码这类功能必须手动集成，跳过任一环节都会导致图片空白或校验失败。
环境与基础依赖
TP8 要求 PHP ≥ 8.0，且必须启用两个底层扩展：
-
GD 库：用于生成验证码图片，检查 php.ini 中
extension=gd是否取消注释，重启服务后可用php -m | grep gd验证 -
OpenSSL：支持 HTTPS 请求及部分加密操作，确认
extension=openssl已启用 - Composer 必须可用，建议切换为阿里云镜像源提升安装速度：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
安装与初始化验证码扩展
TP8 默认不带验证码，需引入官方扩展 topthink/think-captcha：
- 在项目根目录执行：
composer require topthink/think-captcha - 安装成功后运行：
php think captcha:install，该命令会自动生成：
–config/captcha.php（可调整位数、字体、背景色等）
–public/static/captcha/（含前端 JS/CSS 资源） - 验证安装：检查
vendor/topthink/think-captcha目录是否存在，类能正常加载
Session 必须启用且生效
验证码值靠 Session 存储，未启用则 captcha_check() 永远返回 false：
立即学习“PHP免费学习笔记（深入）”；
- 打开
app/middleware.php，确保\think\middleware\SessionInit::class在 middleware 数组中且未被注释 - 不要在控制器里调用
session_start()，它无效；一切依赖中间件自动初始化 - 快速测试：在任意控制器方法中写
session('test', 'ok'); var_dump(session('test'));，输出string(2) "ok"即表示正常
前后端集成方式
避免手动创建图像或拼接响应头，使用框架封装函数更可靠：
-
模板中显示：
{:captcha_img()}自动渲染带时间戳的 img 标签，防缓存；如需点击刷新，用：<img src="{:captcha_src()}" onclick="this.src='{:captcha_src()}'+Math.random()"> -
后端校验：获取输入后务必 trim 去空格，并注意大小写策略：
$input = trim($this->request->post('captcha'));if (!captcha_check($input)) { ... }
默认区分大小写，如需忽略，可统一转大写：captcha_check(strtoupper($input)) - 常见失败原因：输入带空格、Session ID 不一致（跨子域 / http 与 https 混用 / Cookie 被禁）、GD 或 OpenSSL 未启用
