ThinkPHP中验证码生成库在不同版本间的调用差异修复-ThinkPHP-PHP中文网

thinkphp 5.1需手动引入captcha类或通过容器获取，6.x配置结构与参数含义已变更，gd库缺freetype支持、session驱动异常或配置不匹配是验证码失效主因。

thinkphp中验证码生成库在不同版本间的调用差异修复

ThinkPHP 5.1 中 `Captcha` 类无法自动加载

5.1 默认不注册 Captcha 服务，直接 new Captcha() 会报 Class 'think\Captcha' not found。这不是你漏装扩展，而是框架默认不加载该类。

必须手动引入或注册服务：

在控制器里用 use think\captcha\Captcha;，再 new Captcha()
或者更稳妥：用容器获取 think\Container::getInstance()->make('captcha')
别依赖旧版的 think\helper\captcha 路径，5.1 已移除该别名

ThinkPHP 6.x 的 `Captcha` 配置项全变了

6.x 把验证码配置从全局 captcha.php 拆到 config/captcha.php，且键名不兼容 5.x。比如 5.x 的 length 在 6.x 变成 length 仍可用，但 useZh 已废弃，中文验证码需换用 zh 字体路径 + 手动 setFont()。

常见踩坑点：

fontSize 在 6.x 是整数，默认 25；5.x 接受字符串如 '25px'，6.x 传字符串会静默失效
expire 单位从秒变成分钟（6.x 默认 60 分钟），和 session 过期逻辑对不上时，验证码提前失效
调用 Captcha::create() 前必须先 Captcha::config($config)，不能靠 config 文件自动生效

TP5.0 升级到 5.1 后验证码图片空白或 500

核心原因是 GD 库支持变动：5.1 默认启用 imageftbbox（依赖 freetype），而很多 Docker 环境或精简版 PHP 编译时没开 freetype 支持，导致生成失败、返回空响应。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

验证和修复方式：

执行 php -r "var_dump(function_exists('imageftbbox'));"，返回 bool(false) 就是缺 freetype
临时降级方案：在 Captcha 实例上调用 setUseCurve(false)->setUseNoise(false)，避开字体渲染
生产环境务必安装 libfreetype6-dev（Debian/Ubuntu）或 freetype-devel（CentOS），并重编 PHP GD 扩展

验证码校验失败但输入没错

根本原因通常是 session 驱动不一致或未启动。TP5.1+ 默认用 file 驱动，但如果你改过 session.type 为 redis 或 memcache，却没配好连接，Captcha::check() 读不到存储的验证码值，永远返回 false。

排查要点：

检查 session.driver 和对应配置（如 redis.host）是否可连通
Captcha::check() 内部用的是 session('captcha_' . $id)，确保 session 已 start（TP6 要求控制器方法前加 session_start() 或启用中间件）
大小写敏感：前端传的 captcha 值默认转小写比对，但如果你自定义了 reset 行为或用了 useZh，比对逻辑可能不同步