ThinkPHP验证码配置需解决装得上、看得见、验得过三大问题：一、用国内镜像安装扩展并启用GD/openssl；二、开启Session中间件、确认GD支持、验证/captcha路由；三、手动创建UTF-8无BOM的config/captcha.php，严格设置font_path、bg、中文三要素；四、模板用{:captcha_img()}，后端用‘captcha|验证码’=>‘require|captcha’规则校验；五、前后端分离时改用Redis存储验证码实现无状态校验。
ThinkPHP验证码在国内环境配置和使用，核心是解决装得上、看得见、验得过三个问题。国内常见卡点包括 Composer 下载慢、GD 扩展未启用、Session 中间件被注释、HTTPS 混合内容拦截、中文乱码，以及前后端分离下 Session 失效。下面按实际开发顺序给出可直接落地的方案。
一、安装扩展：用国内镜像加速，一步到位
默认 `composer require topthink/think-captcha` 在国内常超时或失败。必须先配置国内镜像：
- 执行命令设置全局镜像：composer config -g repo.packagist https://packagist.phpcomposer.com（TP5/6 均适用）
- 再安装扩展：composer require topthink/think-captcha
- 安装后检查
vendor/topthink/think-captcha目录是否存在，确认无报错 - 若提示
ext-openssl missing，打开php.ini取消;extension=openssl前的分号；同理启用extension=gd
二、基础运行环境：三处必须打开
缺一不可，否则验证码不显示或校验必失败：
-
开启 Session 中间件：打开
app/middleware.php，取消注释这一行：\think\middleware\SessionInit::class -
确保 GD 库可用：在浏览器访问
phpinfo()，搜索gd，确认“GD Support”为 enabled；若无，重启 PHP 服务 -
验证路由是否通：安装后直接访问
/captcha（TP6 默认路由），能返回一张图片即说明基础通路已通
三、配置文件：手动创建 + 关键字段避坑
TP6 不自带 config/captcha.php，必须手动创建，且格式严格：
立即学习“PHP免费学习笔记（深入）”；
- 路径：
config/captcha.php，文件编码为 UTF-8 无 BOM - 最简可用配置（含中文支持）：
return [
'length' => 4,
'useZh' => true,
'zhset' => '你|我|他|好|学|习|思|维|验|证',
'font_path' => __DIR__ . '/../public/fonts/simhei.ttf',
'bg' => [245, 245, 245],
'expire' => 1800
];
-
注意：
font_path必须是绝对路径；bg必须是 RGB 数组，不能写'#f5f5f5'；中文需同时满足useZh、zhset、字体文件三者齐全 - 如需 HTTPS 安全加载，加一项：
'url' => '/captcha/refresh'（避免自动生成 http://）
四、模板与验证：一行调用 + 两种校验方式
前端展示推荐使用助手函数，简洁可靠：
- 在模板中写：
{:captcha_img()}（自动生成 img 标签 + 点击刷新逻辑） - 或手动写：
<img src="{:captcha_src()}" onclick="this.src='{:captcha_src()}?'+Math.random()">
后端验证有两种常用方式：
-
内置验证规则（推荐）：在验证器或控制器中加入规则：
'captcha|验证码' => 'require|captcha' -
手动校验：获取提交值后调用
captcha_check($data['captcha'])，返回布尔值 - 注意：校验前必须确保 Session 已启动，且表单中验证码 input 的
name="captcha"
五、前后端分离场景：绕过 Session 的 Redis 方案
Vue/React 前端独立部署时，Session 因跨域失效。官方扩展默认依赖 Session，此时需替换存储层：
- 不改扩展源码，而是重写校验逻辑：生成验证码时，把验证码文本存入 Redis（key 为随机字符串，如
captcha:abc123），过期时间与expire一致 - 前端请求验证码接口，返回该随机 key 和图片 base64 或 URL；提交登录时，连同 key 和用户输入一起发给后端
- 后端用 key 查 Redis，比对成功后立即删除，实现无状态校验
- 此方案兼容 TP6/TP8，无需禁用 Session，也不依赖 Cookie，适合生产环境 API 化改造
