验证码生成失败主因是GD扩展未启用、Session中间件未开启或响应被污染；需依次检查php -m | grep gd、启用SessionInit中间件、确保路由方法仅返回Captcha::create()。
GD 扩展没启用
验证码图像靠 GD 库绘图，缺了它，Captcha::create() 会静默返回空或报错 Call to undefined function imagecreate()。
- 终端执行 php -m | grep gd，确认有输出
- 若无，打开 php.ini，取消注释 extension=gd（Windows 下可能是 php_gd2.dll）
- Docker 环境需手动安装：apt install libpng-dev libjpeg-dev && docker-php-ext-configure gd --with-jpeg-dir=/usr/include/ && docker-php-ext-install gd
- 改完必须重启 Web 服务（php think run、Apache 或 Nginx）
Session 中间件未启用
TP6 默认不自动初始化 Session，而验证码值存在 $_SESSION 里——没 Session，就根本存不了原始码，后续校验自然全挂。
- 打开 app/middleware.php，找到 \think\middleware\SessionInit::class，删掉行首的 // 注释
- 验证是否生效：在控制器中写 session('test', 'ok'); var_dump(session('test'));，输出 string(2) "ok" 才算成功
- 别依赖 session_start()，框架会忽略它
响应被污染或路由配置不当
验证码接口必须返回纯二进制图像流 + 正确的 Content-Type: image/png。任何额外输出都会破坏图像。
- 生成验证码的路由方法里，只允许一行：return \think\captcha\facade\Captcha::create();
- 禁止 echo、var_dump、json()、模板渲染（return view()）等任何前置/后置输出
- 推荐前端直接用 {:captcha_img()}，它自动生成带时间戳的 <img> 标签防缓存
- 如需自定义路由，严格绑定：Route::get('captcha', [\think\captcha\facade\Captcha::class, 'create']);
