验证码不显示的主因是gd扩展未启用、session未初始化或路由响应头被污染。gd未启会导致create()失败；session未启使check()总为false；响应头含html或无image/png则图片无法渲染。
验证码不显示，90% 是因为 GD 扩展没开、Session 未启用，或路由响应头被意外覆盖。不是配置写错了，而是底层依赖断了。
GD 扩展未启用导致 Captcha::create() 返回空或报错
ThinkPHP 的图形验证码完全依赖 PHP 的 GD 库绘图。如果没启用，Captcha 实例能创建，但调用 create() 或 entry() 时会静默失败（返回空字符串）或抛出 Call to undefined function imagecreate() 类错误。
- 在终端执行
php -m | grep gd，确认输出含gd - 若无输出，需编辑
php.ini，取消注释extension=gd（Windows 下可能是php_gd2.dll），重启 Web 服务 - 注意：部分 Docker 镜像（如
php:8.2-apache）默认不装 GD，需手动apt install libpng-dev libjpeg-dev && docker-php-ext-configure gd --with-jpeg-dir=/usr/include/ && docker-php-ext-install gd
SessionInit 中间件未启用导致验证码值无法写入/读取
Captcha 类内部靠 Session 存储真实验证码文本（比如 4aB9），前端提交的只是用户输入。如果 Session 没初始化，check() 永远返回 false，且生成端可能不报错、只输出空白图片。
- ThinkPHP 6：检查
app/middleware.php是否已取消注释\think\middleware\SessionInit::class - ThinkPHP 5.1：确认
application/tags.php中app_init数组包含\think\middleware\SessionInit::class - 验证方式：在控制器里加一行
session('test', 'ok'); dump(session('test'));，输出null就说明 Session 失效
路由响应头被框架外逻辑污染，导致图片无法渲染
验证码接口（如 /captcha）必须返回纯二进制图像数据，并设置正确的 Content-Type: image/png。一旦中间件、钩子或控制器方法里提前输出了空格、echo、var_dump 或 JSON 响应，图片就会损坏 —— 浏览器显示“图片加载失败”图标，开发者工具 Network 面板里看响应体是乱码或 HTML 片段。
- 禁止在验证码方法里调用
return json(...)、dump()、echo等任何非图像输出 - 确保该路由绑定的是纯生成方法，不要混用视图渲染（如
return view(...)） - 推荐写法：
return Captcha::create();（TP6 facade）或$cap = new Captcha(); return $cap->entry();（TP5/6 实例方式），这两者内部已处理好 header 和输出 - 调试时用
curl -I http://your.site/captcha查看响应头，确认含Content-Type: image/png且无Content-Type: text/html
前端 src 地址拼写错误或缓存未刷新
即使后端一切正常，前端 <img src="..."> 指向错误路径、参数缺失或浏览器强缓存，也会表现为“不显示”。这不是后端问题，但排查时最容易忽略。
- 确保 URL 路由存在且可访问：直接在浏览器地址栏打开
/captcha或你定义的路径，应直接下载或显示一张图 - 避免硬编码路径，用 ThinkPHP 的
{:url('captcha')}（模板）或Url::build('captcha')（PHP）生成 - 点击刷新逻辑必须带随机参数，否则浏览器缓存图片：正确写法是
onclick="this.src='{:url('captcha')}?'+Math.random()"；错误写法是onclick="this.src='{:url('captcha')}'"（无参数，不刷新） - 检查浏览器控制台是否有 404（路径错）、405（方法不支持）、500（后端异常）等状态码
真正卡住的点往往不在验证码配置本身，而在 GD、Session、Header 这三层基础链路上。先逐个验证这三项是否就绪，比反复调参数更省时间。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
