ThinkPHP验证码功能_如何生成和验证图片验证码【操作】-php教程-PHP中文网

thinkphp验证码需手动安装think-captcha扩展并启用session中间件，否则create()返回空白、check()恒为false；验证码图像生成与校验必须在同一session生命周期内完成。

thinkphp验证码功能_如何生成和验证图片验证码【操作】

ThinkPHP 的验证码功能不是开箱即用的独立模块，必须手动安装 topthink/think-captcha 扩展包，并确保 Session 正常工作，否则 create() 会返回空白图像、check() 永远返回 false。

安装扩展并确认 Session 已启用

从 ThinkPHP 5.1 开始，验证码不再内置，必须通过 Composer 安装。同时，think-captcha 严重依赖 Session 存储原始验证码值，若 Session 未初始化，整个流程直接失效。

执行 composer require topthink/think-captcha 安装扩展
检查 app/middleware.php 中是否已启用 \think\middleware\SessionInit::class（TP6 默认注释掉，需取消注释）
在控制器或中间件中调用 session_start() 不起作用 —— 必须靠中间件自动启动，否则 $_SESSION 不可用
验证 Session 是否生效：在任意控制器方法中写 session('test', 'ok'); var_dump(session('test'));，输出 string(2) "ok" 才算正常

生成验证码图像时必须用 `captcha_img()` 或正确路由绑定

直接在控制器里 new Captcha()->create() 并 return，容易因响应头/输出顺序问题导致图像损坏（浏览器显示“无法加载图像”）。更稳妥的方式是让框架自动处理输出流。

PHP 8.5.5

PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。

下载

推荐在模板中直接使用 {:captcha_img()}，它会自动生成带随机参数的 <img src="/captcha?_=%7Btime%7D"> 标签
若需自定义路由，必须在路由定义中绑定到一个仅输出图像的方法，例如：Route::get('captcha', [\think\captcha\facade\Captcha::class, 'create']);
不要在该方法中做任何 echo/print/dump 输出，哪怕一个空格或换行都会破坏 PNG/JPEG 流
如果使用 Captcha::create() 手动调用，必须确保当前响应未被其他内容提前输出（常见于布局模板中意外空行）

`check()` 失败的三大高频原因

captcha_check($input) 或 (new Captcha())->check($input) 返回 false，90% 不是逻辑错，而是环境或调用时机问题。

用户提交的是空字符串或全空格 —— 前端未 trim，建议先 trim($input) 再校验
Session ID 不一致：登录页和提交页跨域、或用了不同子域名，导致两次请求 session_id() 不同，验证码存一份、查另一份
验证码已被消耗：ThinkPHP 默认一次有效，check() 成功后自动清除 session 中的值；若页面 JS 重复提交、或刷新后重试旧值，必然失败
大小写敏感：默认配置下，check() 区分大小写；若前端输入全小写但生成的是大写字母，需统一转大写再比对，或配置 'useZh' => false, 'useLower' => true

自定义配置必须传给构造函数，不能改全局静态属性

很多人试图通过 Captcha::$config['length'] = 6 修改位数，这完全无效 —— 配置只在实例化时读取一次，后续修改不生效。

正确方式是传入数组：$captcha = new Captcha(['length' => 6, 'useNoise' => true, 'expire' => 300]);
常用配置项：length（长度）、useNoise（噪点）、useCurve（扭曲曲线）、imageH/imageW（尺寸）、expire（秒级有效期）
expire 设为 0 表示永不过期，但极不安全；设太短（如 60 秒）可能导致用户填完还没点提交就失效
字体文件路径错误会导致文字不显示（只看到方块），此时需确认 fontttf 配置指向真实存在的 .ttf 文件，且 Web 进程有读取权限

最易被忽略的一点：验证码图像生成和校验必须发生在同一个 Session 生命周期内，而 Session 的生命周期又受 session.gc_maxlifetime 和 Cookie 过期时间双重控制。如果服务器 PHP 配置中 session.gc_maxlifetime 小于验证码 expire，那验证码实际存活时间永远等于前者。