TP5.1升级后验证码不显示，主因是GD库未启用（尤其缺FreeType支持）、字体路径大小写不匹配、runtime/session目录权限不足或ob缓冲干扰；需逐项验证GD状态、字体文件存在性、输出缓冲及session可写性。
TP5.1 升级后验证码不显示，大概率不是框架升级本身的问题，而是 GD 库状态变化、字体路径大小写敏感、或 runtime/session 目录权限在新环境里被重置了。Windows 下尤其容易因路径大小写（如 Captcha.php vs captcha.php）或字体文件名不匹配直接返回空白图。
GD 库是否真启用？别只看 phpinfo()
升级 PHP 或 TP5.1 后，extension=gd 可能被自动注释，或启用了 GD 但没加载 FreeType 支持——这会导致 ThinkPHP5 验证码生成时 silently 失败（无报错，只返回黑块或小叉）。Win10/11 默认集成环境（如 phpstudy）常预装精简版 GD，缺 FreeType 就无法渲染文字。
- 检查
php.ini中是否同时启用了：extension=gd和（关键）extension=php_gd2.dll（Windows）或确认gd.jpeg_ignore_warning等配置项存在 - 运行
php -m | findstr gd（Windows）或php -m | grep gd（Linux），确认输出含gd；再执行php -r "var_dump(gd_info()['FreeType Support']);"，必须返回bool(true) - 若为 false，需重新编译 GD 或换用含 FreeType 的 PHP 包（如 XAMPP 新版、WAMP Server 3.3+）
字体路径大小写错误：Windows 下静默失败
ThinkPHP5 验证码默认使用 think-captcha 的 font\captcha.ttf，但升级后 vendor 包可能被重装，字体路径变成 Font\captcha.ttf 或 FONT/captcha.TTF——Windows 文件系统不区分大小写，但 PHP 的 file_exists() 在某些 PHP 版本（尤其 7.4+）下会因 realpath 缓存或 opcache 导致大小写校验失败，最终 imagettftext() 报错并返回空图像。
- 打开
vendor\topthink\think-captcha\src\Captcha.php，找到$this->font赋值行（通常在__construct()或create()中），硬编码指定绝对路径测试：$this->font = __DIR__ . '/font/captcha.ttf'; - 用
var_dump(file_exists($this->font));打印验证，确保返回true；若为 false，检查实际文件名大小写，并同步修正路径 - 避免使用相对路径或
APP_PATH拼接，优先用__DIR__定位
ob_clean() 不是万能解，但得用对地方
ob_clean() 的作用是清空输出缓冲区，防止前面的空格、BOM、echo 或 warning 干扰二进制图像流。TP5.1 升级后，若控制器基类、中间件或公共函数中新增了调试输出（比如日志埋点、dump()），就容易触发此问题。但它不能解决 GD 缺失或字体路径错误这类底层问题。
- 仅在验证码生成方法（如
verify()）开头加：ob_clean();，不要加在中间件或构造函数里 - 确认该方法是独立响应（不嵌入 HTML），且没有前置
echo、print_r()、未捕获的 warning（可临时加error_reporting(0);测试） - 若用了注解路由，确保注解没触发额外初始化逻辑（如自动加载模型导致输出）
最易被忽略的是：升级后 runtime 目录权限重置，或 Session 存储路径指向不可写位置，导致验证码虽生成成功但 session 写入失败，后续验证永远不通过——此时图片能显示，但输入总提示错误。务必用 var_dump(session_status() === PHP_SESSION_ACTIVE); 和 is_writable(session_save_path()); 交叉验证。
