ThinkPHP6 前后端分离实践：基于Redis的图形验证码接口设计与实现

最新推荐文章于 2026-06-23 11:43:24 发布

原创

最新推荐文章于 2026-06-23 11:43:24 发布 · 715 阅读

标签

#ThinkPHP6 #前后端分离 #图形验证码 #Redis

1. 为什么前后端分离项目需要改造验证码？

如果你刚开始接触ThinkPHP6的前后端分离项目，可能会在验证码这块儿卡住。官方自带的think-captcha扩展确实好用，一行代码就能出图，但它有个“历史包袱”——它依赖PHP的Session来存储和校验验证码。

在传统的不分离项目里，这没问题，因为浏览器每次请求都会自动带上Cookie里的Session ID，服务端能轻松找到对应的Session数据。但前后端分离后，情况变了。你的前端可能是Vue、React或小程序，它们通过API接口与ThinkPHP后端通信，这种通信通常是无状态的，比如使用JWT（JSON Web Token）来鉴权，根本用不上Session。这时候，如果你直接调用Captcha::create()，生成的验证码虽然能显示，但校验时永远对不上，因为后端找不到存储验证码的那个Session了。

我刚开始做分离项目时就踩过这个坑，页面上的验证码明明输对了，却一直提示错误，调试了半天才发现是Session隔离导致的。所以，核心问题就变成了：我们需要一个独立于Session的、高性能的存储介质来存放验证码，并在生成和校验时能精准存取。

这就是引入Redis的原因。Redis是一种内存数据库，读写速度极快，而且支持设置键值对的过期时间，完美契合验证码“用后即焚”和“短期有效”的特性。把验证码文本存到Redis里，生成时返回一个唯一的token（作为Redis的key）给前端，校验时前端再把这个token和用户输入的验证码一起传回来，后端用这个token去Redis里取出正确的验证码进行比对。整个流程清晰、安全，且完全解耦了前后端的状态管理。

2. 项目环境准备与核心依赖安装

工欲善其事，必先利其器。在开始写代码之前，我们得先把环境和依赖准备好。这里假设你已经有一个正在开发的ThinkPHP6项目了。

第一步：确保Redis已安装并运行 这是我们的“仓库”。如果你用的是Linux，通常可以通过包管理器安装，比如sudo apt install redis-server（Ubuntu）或sudo yum install redis（CentOS），安装后记得启动服务：sudo systemctl start redis。在Windows上，可以从GitHub下载微软维护的Redis版本。安装好后，在命令行输入redis-cli ping，如果返回PONG，说明Redis服务运行正常。

第二步：在ThinkPHP6项目中安装验证码扩展和Redis驱动 打开你的项目根目录，在命令行执行以下命令：

composer require topthink/think-captcha
composer require topthink/think-redis

第一个命令安装了官方的图形验证码生成库，我们主要用它来生成图片和验证码字符串，但不用它的Session存储逻辑。第二个命令安装了ThinkPHP官方维护的Redis扩展，它提供了与框架完美集成的缓存和门面操作方式。

第三步：配置Redis连接 安装完成后，需要配置Redis的连接信息。打开项目下的config/cache.php文件，找到stores配置项，添加或修改redis的配置：

return [
    // 默认缓存驱动
    'default' => env('cache.driver', 'file'),

    // 缓存连接方式配置
    'stores' => [
        'file' => [
            // 文件缓存配置...
        ],
        // 增加或修改redis配置
        'redis'   =>  [
            'type'     => 'redis',
            'host'     => env('redis.host', '127.0.0.1'),
            'port'     => env('redis.port', 6379),
            'password' => env('redis.password', ''),
            'select'   => env('redis.select', 0), // 默认选择0号数据库
            'timeout'  => 0, // 连接超时时间（秒）
            'prefix'   => env('redis.prefix', 'tp6:'), // 键名前缀，防止冲突
        ],
    ],
];

我习惯使用环境变量来管理配置，这样在不同环境（开发、测试、生产）切换起来很方便。在项目根目录的.env文件中，你可以这样设置：

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_SELECT=0
REDIS_PREFIX=tp6:captcha:

注意我给前缀加上了captcha:，这样所有验证码相关的Redis键都会以tp6:captcha:开头，一目了然，也方便后期维护或清理。

3. 核心改造：生成并存储验证码接口

环境配好了，现在进入实战环节。我们要创建一个API接口，它不仅能生成验证码图片，还要把验证码文本安全地存到Redis里。

首先，在某个控制器里（比如app/controller/Captcha.php），创建生成验证码的方法。我直接上代码，然后一步步解释：

<?php
namespace app\controller;

use app\BaseController;
use think\captcha\facade\Captcha;
use think\facade\Cache;

class Captcha extends BaseController
{
    /**
     * 生成图形验证码接口
     * @return \think\response\Json
     */
    public function create()
    {
        // 1. 调用Captcha门面生成验证码，并启用API模式
        $captchaData =

最低0.47元/天解锁文章