如何配置ThinkPHP中的ThinkCaptcha验证码模块？

本文共计749个文字，预计阅读时间需要3分钟。

如果您在ThinkPHP项目中需要集成图形验证码功能以增强表单的安全性，但尚未配置或使用think-captcha扩展，则可能无法显示或验证验证码。以下是实现ThinkCaptcha验证码配置与使用的具体步骤：

一、安装think-captcha扩展包

think-captcha是ThinkPHP官方维护的独立验证码扩展，依赖GD库和Session机制，必须通过Composer安装才能使用。未安装将导致类找不到或调用失败。

1、在项目根目录执行以下命令安装扩展：composer require topthink/think-captcha

2、安装完成后检查vendor/topthink/think-captcha目录是否存在，确认扩展已成功载入。

立即学习“PHP免费学习笔记（深入）”；

3、若提示GD扩展未启用，请在php.ini中取消extension=gd注释并重启Web服务器。

二、启用Session中间件

验证码校验依赖Session存储原始验证码值，若Session未初始化，无论输入是否正确均会返回失败。ThinkPHP6默认禁用Session中间件，需手动启用。

1、打开app/middleware.php文件

2、找到\think\middleware\SessionInit::class这一行

3、删除该行开头的注释符号//，使其变为可执行状态：\think\middleware\SessionInit::class

三、配置验证码参数

可通过全局配置文件统一设定验证码行为，避免每次实例化重复传参。配置项直接影响安全性与用户体验，如过期时间、干扰强度、字符集等。

1、在config/目录下新建captcha.php文件

2、写入以下标准配置数组（可根据需要调整）：return [ 'length' => 4, 'expire' => 1800, 'useNoise' => true, 'useCurve' => true, 'fontSize' => 25, 'imageW' => 130, 'imageH' => 50 ];

3、确保配置键名与think-captcha文档一致，非法键将被忽略。

四、生成并展示验证码图像

验证码图像需通过控制器方法输出二进制流，前端img标签通过src属性请求该接口实现动态加载。直接echo或return字符串会导致图像损坏。

1、在控制器中添加方法，例如app/controller/Index.php内定义captcha()：

2、方法体内写入：return \think\captcha\facade\Captcha::create();

3、在模板HTML中插入图像标签：<img src="{:url('index/captcha')}" alt="验证码" onclick="this.src='{:url('index/captcha')}?'+Math.random()" />

五、验证用户提交的验证码

校验过程必须在接收POST数据的控制器动作中完成，且须确保Session已启动。有三种主流校验方式，适用于不同开发场景。

1、使用全局函数captcha_check()（最简方式）：if (!captcha_check(input('post.vcode'))) { return json(['code'=>0,'msg'=>'验证码错误']); }

2、使用控制器内置validate()方法（支持自定义错误提示）：$this->validate(input('post.'), ['vcode|验证码'=>'require|captcha']);

3、使用独立验证器类（适合多模块复用）：app\validate\CaptchaValidate::make()->check(input('post.'));