Win10/11下ThinkPHP5验证码不显示避坑排错与修复指南【解答】-ThinkPHP-PHP中文网

thinkphp5验证码在win10/11不显示主因是gd库未配全（freetype未启用）、字体文件路径/权限异常、输出被bom或错误提示污染、路由配置不匹配；需依次检查并修复这四类环境问题。

win10/11下thinkphp5验证码不显示避坑排错与修复指南【解答】

ThinkPHP5验证码在Win10/11环境下不显示，90%以上不是代码问题，而是本地开发环境配置或文件细节被忽略。Windows系统对BOM、路径编码、字体读取更敏感，加上默认PHP集成环境（如phpstudy、XAMPP、WAMP）常预装不完整GD库，导致验证码返回空白、小叉号或黑块。下面按高频真实场景分项说明。

GD扩展与FreeType支持必须双启用

TP5验证码依赖imagettftext()绘制文字，该函数要求GD扩展不仅已加载，还必须开启FreeType支持——很多Windows一键包（如旧版phpstudy）只启用了GD，但FreeType为false。

运行php -r "var_dump(gd_info()['FreeType Support']);"，确认输出bool(true)；若为false或报错，说明FreeType未就绪
打开php.ini，确保extension=gd已取消注释；部分Windows环境还需手动启用extension=php_gd2.dll
重启Web服务后，访问phpinfo()页面搜索“FreeType”，看到“FreeType Version”且值非空才算真正生效

字体文件路径与权限要“零容错”

TP5默认用simhei.ttf，但Windows下若字体文件被杀毒软件拦截、路径含中文、或文件本身损坏，imagettftext()会静默失败，只输出纯背景图。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

检查字体实际位置：TP5通常从vendor/topthink/think-captcha/src/assets/simhei.ttf加载；建议复制到public/static/font/DejaVuSans.ttf（开源无版权，兼容性更好）
在config/captcha.php中显式指定：'font' => public_path('static/font/DejaVuSans.ttf')
右键字体文件 → “属性” → 取消勾选“只读”，并确认当前运行PHP的用户（如IIS_IUSRS或Everyone）有读取权限

输出污染是Windows最常见“隐形杀手”

验证码是纯二进制图像流，前面哪怕一个空格、UTF-8 BOM头、或Notice警告，都会让浏览器解析失败。Windows记事本、VS Code默认保存带BOM的UTF-8文件，极易中招。

用Notepad++或VS Code打开app/controller/YourLogin.php、public/index.php及所有被include的配置文件，编码→转为“UTF-8无BOM格式”并保存
在验证码方法开头强制清理缓冲：ob_clean();（注意不是ob_end_clean()），再调用$captcha->entry()
临时关闭错误提示：在入口文件顶部加ini_set('display_errors', '0');，避免Undefined variable等Notice干扰输出

路由与伪静态需匹配本地IIS/Apache规则

Win10/11常用IIS或XAMPP Apache，若URL重写未正确配置，请求/captcha会被当成目录访问而404，或误走index.php路由逻辑。

直接在浏览器访问http://localhost/index.php?s=captcha（TP5默认路由模式），能显示图即说明核心功能正常；不能则先查路由是否被伪静态规则截断
IIS用户请确认web.config中已添加ThinkPHP重写规则，重点检查<rule name="ThinkPHP" stopprocessing="true"></rule>段是否启用
XAMPP用户检查httpd.conf是否启用了mod_rewrite，且AllowOverride All已配置到项目目录

Windows环境修复验证码，关键不在改代码，而在清BOM、验GD、换字体、查路由这四步闭环。每步验证一次，基本就能定位到那个被忽略的“小地方”。