ThinkPHP8 验证码需通过 topthink/think-captcha 扩展集成，关键在于采用 key+缓存机制替代 session 依赖，适配前后端分离场景；配置需启用 gd/openssl、Session 中间件及合理 captcha.php 参数；安全上须实现一次有效、上下文绑定、限频与大小写不敏感校验。
ThinkPHP8 中验证码不是开箱即用的功能，但通过 topthink/think-captcha 扩展可快速集成。关键不在“装上”，而在“用对”——尤其在前后端分离、跨域、API 场景下，必须绕过 session 依赖，改用 key + 缓存机制，否则登录接口会频繁验证失败。
安装与基础配置：三步到位
安装扩展包是第一步，但仅执行 composer require topthink/think-captcha 不够，还需确认三项环境支持：
- 开启 PHP 的
gd扩展（生成图片必需），修改php.ini并重启服务 - 开启
openssl扩展（部分字体/编码操作依赖） - 在
app/middleware.php中启用 Session 中间件：\think\middleware\SessionInit::class
配置文件位于 config/captcha.php，建议明确设置：'length' => 4（位数）、'expire' => 300（5分钟过期）、'useNoise' => true（增强防识别）。不推荐开启 math 或 useZh，兼容性和前端解析成本高。
前后端分离下的验证码流程设计
传统 captcha_img() 依赖 PHPSESSID 写入 session，在跨域请求中无法共享 cookie，导致后端校验时取不到原始验证码。正确做法是：后端生成唯一 key，把验证码值存入缓存（如 Redis 或 TP 自带 cache），前端提交时携带该 key 和用户输入值。
立即学习“PHP免费学习笔记（深入）”；
- 后端生成接口返回 JSON：
{ "key": "captcha_xxx", "img": "data:image/png;base64,..." } - 前端将
key存入表单数据（如ruleForm.captchaKey），和用户输入的code一并提交 - 登录接口调用
Captcha::check($code, $uuid)，其中$uuid即前端传来的 key
该模式彻底解耦 session，适配 Nginx 反向代理、微服务网关、多实例部署等真实生产环境。
安全加固要点：防重放、防爆破、防绕过
验证码不是摆设，需配合策略才能真正起效：
-
一次有效：验证通过后立即删除缓存（
cache($key, null)或$redis->del("captcha:$key")） -
绑定上下文：若已知用户手机号或设备指纹，可将 key 拼接该标识（如
"captcha_{$phone}_{$uuid}"），防止 key 被复用 - 限频控制：对同一 IP 或手机号，1 分钟内最多请求 3 次验证码，超限返回 429
-
大小写不敏感校验：后端统一转小写比对（
mb_strtolower($input, 'UTF-8')），避免前端未处理导致失败
常见问题速查与修复
遇到“验证码始终错误”，先排查这四点：
- 是否漏掉
SessionInit中间件？即使不用 session 存验证码，框架内部仍可能依赖 session 初始化流程 - 前端传的
key是否和服务端生成的完全一致？注意 URL 编码、空格、大小写 - 缓存驱动是否正常？如使用 file 缓存，在 CLI 模式（
php think run）下可能路径权限异常；推荐切换为 redis - 验证码图片 base64 前缀是否被前端误删？应保留完整
data:image/png;base64,...字符串用于展示
调试时可在生成验证码后立刻 dump(cache($key))，确认缓存写入成功且值正确。
