thinkphp5验证码需三步到位：一、按版本严格匹配安装（tp5.0用=1.，tp5.1用=2.）；二、手动执行php think captcha:install发布配置与资源；三、启用session中间件并验证可用，缺一即导致create()空白或check()恒false。
ThinkPHP 5 系统已停止官方维护（自2021年起），但大量线上项目仍在稳定运行。截至2026年，TP5.0 和 TP5.1 仍可正常使用验证码功能，关键不是“最新版”，而是**版本严格匹配 + 手动补全缺失环节**。直接执行 composer require topthink/think-captcha 极大概率失败——因为默认会拉取 v4+（适配 TP6/8），与 TP5 不兼容。
一、确认你的 ThinkPHP 5 具体小版本
打开项目根目录下的 composer.json，查看 "topthink/framework" 的版本号：
- TP5.0.x（如 5.0.24）→ 必须用
think-captcha=1.* - TP5.1.x（如 5.1.41）→ 必须用
think-captcha=2.* - 若误装 v3/v4，会出现
Class 'think\captcha\Captcha' not found或Declaration of ... must be compatible with ...
二、命令行安装（含国内镜像加速）
在项目根目录（含 composer.json）中执行以下命令：
-
TP5.0 安装（推荐带 -vvv 查看详细报错）：
composer require topthink/think-captcha=1.* -vvv -
TP5.1 安装：
composer require topthink/think-captcha=2.* -vvv - 如遇超时或慢速，先设国内镜像（一次设置，全局生效）：
composer config -g repo.packagist composer https://packagist.laravel-china.com - 验证是否成功：
检查vendor/topthink/think-captcha/src/Captcha.php是否存在；
运行php think version确认框架版本无误
三、手动发布配置与静态资源
Composer 安装后不会自动写入配置文件或前端资源，必须主动执行：
- 运行命令：
php think captcha:install - 检查是否生成：
✅config/captcha.php（若无，需手动创建并填入基础数组）
✅public/static/captcha/目录，内含captcha.js、captcha.css、images/ - 若提示
Command "captcha:install" is not defined，说明服务提供者未注册：
打开config/app.php，在'providers'数组末尾添加：\think\captcha\CaptchaServiceProvider::class,
四、启用 Session 并校验前置条件
验证码值依赖 Session 存储，缺此一步，captcha_check() 永远返回 false：
- 确保
app/middleware.php中启用了 Session 中间件：think\middleware\SessionInit::class（TP5.1）或think\middleware\Session::class（TP5.0） - 检查
config/session.php中'type'不为none，推荐用file或redis - 在控制器中测试 Session 是否可用：
session('test', 'ok'); dump(session('test'));→ 应输出'ok'
不复杂但容易忽略：版本锁死、资源手动发布、Session 中间件启用，这三步缺一不可。装完跑不起来，90% 出在这三个地方。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
