ThinkPHP 5.1 验证码图片不显示？检查 GD 库安装与输出缓冲设置

ThinkPHP 5.1 的验证码突然不显示了，别急着翻代码——这事儿十有八九是服务器环境在使绊子。原因多半在哪？GD 库没装全、FreeType 支持没开、字体文件路径错了、输出缓冲区被 BOM 头或错误提示悄悄污染，再不然就是缓存目录不可写。这四个环节任何一个出差错，验证码就会变成空白一片，或者直接给你个红叉。

好，我们来拆解一下。先从最常见的坑说起。

确认 GD 扩展已启用且支持 TrueType

第一步很直接：在命令行敲一句 php -m | grep gd，如果没有任何输出，说明 GD 扩展根本没加载，后面的都别想了。

第二步，也是关键一步：运行 php -r "var_dump(gd_info()['FreeType Support']);"，输出必须是 bool(true)。如果是 bool(false)，imagettftext() 将彻底罢工，验证码必然一片空白。

Linux 系统下补 FreeType 支持很简单：Ubuntu/Debian 执行 sudo apt install libfreetype6-dev，CentOS 执行 sudo yum install freetype-devel。如果你是源码编译的 PHP，重编时必须加上 --with-freetype（记住，新版 PHP 已经不再认 --with-freetype-dir 这个旧参数了）。

清除输出缓冲并屏蔽干扰输出

很多时候问题出在输出被意外污染了。解决方法也不复杂。

方法一：在生成验证码的控制器方法前面，直接插一行 ob_clean();。这招是 ThinkPHP 官方文档明确推荐的，不是可选项，是必须做的。

方法二：在验证码方法开头加一句 ini_set('display_errors', 'off');，防止 PHP 抛出的 Notice 或 Warning 悄悄混进图像流里。

方法三：检查两个文件——public/index.php 和控制验证码的那个控制器文件，看是不是带上了 UTF-8 BOM。用 VS Code 打开，看右下角编码显示，如果是 "UTF-8 with BOM"，点一下切换成 "UTF-8 without BOM" 保存就行。

这里有个小陷阱得注意：千万别用 ob_end_clean() 替代 ob_clean()。前者会直接关闭输出缓冲区，后者只清空内容但保持开启状态——这才是验证码需要的正确姿势。

验证字体文件存在性与权限

TP5.1 默认用的字体文件是 thinkcaptchaassetsfont1.ttf。先确认这东西真实存在：ls -l think/captcha/assets/font/1.ttf。

如果文件确实在，但验证码仍然是空白的，那大概率是 Linux 系统下读不了这个字体。imagettftext() 对中文路径、带空格的路径、文件名里藏着 BOM 的情况极其敏感。绝对不要从 Windows 复制 simhei.ttf 之类的字体来用——这种跨平台的坑踩过的人不少。

稳妥的做法是换成开源无版权的字体，比如 DejaVuSans.ttf（从 fonts.google.com 下载）。把它放到 public/static/font/ 目录，然后在配置里显式指定路径：'font' => public_path('static/font/DejaVuSans.ttf')。

最后，别忘了检查 Web 进程用户（通常是 www-data 或 nginx）有没有读权限：chmod 644 public/static/font/DejaVuSans.ttf。

检查 runtime/cache/captcha 目录可写

这是最后一道防线了。验证码依赖这个目录来缓存数据，如果不可写，一切白搭。

第一步：ls -ld runtime/cache/captcha，确认目录存在且权限包含 w。如果显示的是 drwxr-xr-x，那表示不可写，需要修复。

第二步：如果目录压根不存在，手动创建：mkdir -p runtime/cache/captcha。

第三步：赋予 Web 用户写权限。Ubuntu/Debian 用 chown -R www-data:www-data runtime/cache，CentOS 用 chown -R nginx:nginx runtime/cache。

第四步：也是偶尔会遇到的问题——磁盘满了。跑一下 df -h，看看 /var 或项目所在分区的剩余空间。空间不足时，验证码缓存写不进去，表现也是空白。