ThinkPHP验证码功能不内置，必须安装topthink/think-captcha扩展：TP5.0用=1.，TP5.1用=2.，TP6/8用无版本号命令；安装后需执行php think captcha:install发布配置，并确保Session已启用，否则create()返回空白、check()恒为false。
ThinkPHP 验证码功能不内置，必须通过官方扩展包 topthink/think-captcha 安装启用。2026 年主流版本（TP5.1、TP6.x、TP8.x）均使用 Composer 管理，安装逻辑清晰，但版本匹配和 Session 启用是两大关键点，错一步就无法显示或校验。
确认 ThinkPHP 版本并选对验证码包
不同主版本对应不同扩展包分支，混用会导致类加载失败或方法不存在：
- ThinkPHP 5.0 → 必须用
topthink/think-captcha=1.* - ThinkPHP 5.1 ~ 5.2 → 必须用
topthink/think-captcha=2.* - ThinkPHP 6.x / 8.x → 直接用
topthink/think-captcha（自动拉取最新兼容版，当前为 v4.x）
执行 php think version 或查看 thinkphp/library/think/Env.php 中的 VERSION 常量，确认实际版本号再操作。
命令行安装（Composer）全流程
所有操作均在项目根目录（含 composer.json 和 think 可执行脚本）下运行：
立即学习“PHP免费学习笔记（深入）”；
- TP5.0：
composer require topthink/think-captcha=1.* - TP5.1：
composer require topthink/think-captcha=2.* - TP6/TP8：
composer require topthink/think-captcha
安装成功后，检查 vendor/topthink/think-captcha/src/Captcha.php 是否存在。再临时加一行测试代码：dump(class_exists('think\captcha\Captcha'));，输出 true 表示类已加载。
发布配置与静态资源
扩展包不会自动写入配置或前端文件，必须手动执行安装脚本：
- 运行：
php think captcha:install - 检查是否生成
config/captcha.php（若无，需手动创建并写入基础数组） - 确认
public/static/captcha/下有captcha.js、captcha.css和images/目录
常见问题：该命令报错“command not found”？说明服务提供者未注册——TP5.1+ 需检查 config/app.php 的 providers 数组是否含 \think\captcha\CaptchaServiceProvider::class；TP6/8 则由框架自动发现，无需手动加。
启用 Session 并验证前端调用
验证码值依赖 Session 存储，未启用 Session 中间件时，Captcha::check() 永远返回 false：
- TP6/8：确保
app/middleware.php中启用了SessionInit中间件（默认已开启） - TP5.1：检查
app.php中'middleware' => ['session']是否配置
模板中调用方式（以 TP6 为例）：
- 显示图片：
{:captcha_img()}或<img src="{:captcha_src()}" onclick="this.src='{:captcha_src()}?'+Math.random()"> - 表单提交后校验：
Captcha::check($request->post('captcha'))
若图片 404，请直接访问 /captcha.html 或 /captcha 路由，看是否能出图；不能则优先排查路由定义与 public 目录权限。
