验证码不显示主因是gd库未配全或输出被污染：gd扩展未启用、freetype支持缺失、字体文件不可读或路径非法、输出缓冲区被空格/bom/错误提示污染、缓存目录不可写。
验证码不显示，90% 以上是 GD 库没配全或输出被污染，不是代码写错了。
GD 扩展未启用或缺少 FreeType 支持
ThinkPHP 的 captcha 组件依赖 imagettftext() 渲染文字，而该函数必须在 GD 启用且 FreeType Support 为 true 时才可用。否则会返回空白图、黑块，甚至直接报 Call to undefined function imagettftext()。
- 运行
php -m | grep gd确认 GD 已加载 - 运行
php -r "var_dump(gd_info()['FreeType Support']);"，输出必须是 bool(true) - Linux 上常见缺失：CentOS 用
yum install freetype-devel，Ubuntu/Debian 用apt install libfreetype6-dev - 若 PHP 是源码编译的，重编时必须加
--with-freetype（新版不再支持--with-freetype-dir）
字体文件不可读或路径不合法
TP5 默认用 simhei.ttf，TP6 默认用 vendor/topthink/think-captcha/src/assets/simhei.ttf；但很多 Linux 环境下这个字体根本打不开——不是缺字，是 imagettftext() 静默失败，只画个空背景。
- 检查字体文件是否存在：
ls -l public/static/font/simhei.ttf（TP6 常放这里）或ls -l vendor/topthink/think-captcha/src/assets/simhei.ttf - 换成开源无版权的
DejaVuSans.ttf（可从 fonts.google.com 下载），并显式配置：'font' => public_path('static/font/DejaVuSans.ttf') - 确保 Web 进程用户（如
www-data或nginx）有读权限：chmod 644 *.ttf - 绝对不要用中文路径、空格路径或带 BOM 的 UTF-8 文件名——
imagettftext()对路径编码极敏感
输出缓冲区被提前污染
验证码是纯二进制图像流，前面哪怕一个空格、BOM 头、echo 或 PHP 错误提示（如 Notice），都会导致浏览器解析失败，显示为小叉号或损坏图。
- 在控制器中调用
$captcha->entry()前，加一句ob_clean();（不是ob_end_clean()） - 确认入口文件（
public/index.php）和验证码方法所在文件**没有 UTF-8 BOM**；用file -i filename检查，或用 VS Code / Sublime 保存为 “UTF-8 without BOM” - 临时关闭错误输出：
ini_set('display_errors', 'off');，避免 Notice/Warn 干扰图像流 - 不要在生成验证码的方法里混 HTML 输出，它必须是独立响应
缓存目录不可写或字体缓存失败
TP 的 Ttf 驱动首次加载字体时，会解析成位图缓存到 runtime/cache/captcha/。如果该目录不可写，就会卡住、500 或抛出 file_put_contents(): failed to open stream。
- 检查权限：
ls -ld runtime/cache，确保 Web 用户可写；测试：touch runtime/cache/test && rm runtime/cache/test - Docker 环境注意挂载参数：避免
noexec或nosuid导致缓存写入失败 - SELinux 启用时可能拦截，临时用
setenforce 0测试是否为此原因 - 不想处理缓存？配置里加
'use_cache' => false（TP6），性能影响微乎其微
真正难排查的点往往不在代码里，而在 GD 的 FreeType 支持状态、字体文件的实际可访问性、以及输出缓冲是否干净——这三者任何一个出问题，都只会给你一个“小叉号”，不会报错，也不会提示。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
