验证码空白主因是GD未启用、输出干扰或响应头错配；需确认php -m含gd、文件UTF-8无BOM、header与imagepng严格匹配，并验证Session是否正常写入。
PHP 8.2 环境下验证码图片在浏览器中完全空白、显示为损坏图标或提示“无法加载图像”，不是配置写错，而是底层图像生成链路在某个环节被截断。
确认 GD 扩展已启用且兼容 PHP 8.2
GD 是验证码绘图的唯一依赖，PHP 8.2 默认不启用 GD，Docker 镜像（如 php:8.2-apache）甚至根本不预装。
执行 php -m | grep gd，若无任何输出，说明 GD 未加载。
编辑 php.ini，取消注释 extension=gd（Windows 下为 extension=php_gd2.dll），保存后重启 Apache/Nginx。
立即学习“PHP免费学习笔记（深入）”；
若使用 Docker，需在构建阶段显式安装：运行 apt update && apt install -y libpng-dev libjpeg-dev libfreetype6-dev，再执行 docker-php-ext-configure gd --with-jpeg-dir=/usr/include/ --with-freetype-dir=/usr/include/ → docker-php-ext-install gd。跳过 configure 步骤会导致 JPEG 支持缺失，验证码用 imagejpeg() 时静默失败。
【必须验证】 访问 phpinfo() 页面，Ctrl+F 搜索 gd，确认 “GD Version” 显示非空值（如 “bundled (2.1.0 compatible)”），且 “PNG Support”、“JPEG Support” 均为 enabled。
清除 BOM 头与前置输出干扰
UTF-8 编码的 PHP 文件若带 BOM（字节顺序标记），会在 header() 调用前自动输出三个不可见字节，直接破坏图片二进制流。
方法一：用 VS Code 或 Notepad++ 打开验证码脚本（如 captcha.php），右下角查看编码格式，若显示 “UTF-8 with BOM”，点击切换为 “UTF-8” 并保存。
方法二：在脚本最顶部第一行、<?php 之前**绝对不能有任何字符**——包括空格、Tab、换行。常见错误是编辑器自动在文件末尾加空行，或从其他文件复制代码时带入隐藏符号。
方法三：在 header("Content-Type: image/png") 前插入 ob_clean(); 强制清空输出缓冲区。这能兜底解决部分框架或 include 文件引入的意外输出，但只是补救，根源仍在编码和空白字符。
注意：不要在验证码脚本里调用 echo、var_dump()、print_r() 或任何会触发输出的函数；也不要在它之前 include 含 HTML 输出或调试语句的文件。
检查响应头与输出函数是否严格匹配
浏览器靠 Content-Type 头识别响应体类型，一旦错配，图片就无法渲染。
第一步：用 curl -I http://your.site/captcha.php 查看响应头，确认返回 Content-Type: image/png（或 image/jpeg），且**没有同时出现 Content-Type: text/html**。
第二步：核对 PHP 代码中的输出函数与 header 声明是否一致——header("Content-Type: image/png") 必须配 imagepng($im)；header("Content-Type: image/jpeg") 必须配 imagejpeg($im)。混用会导致输出乱码。
第三步：确保 $im 图像资源有效。在 imagepng($im) 前加一句 if (!$im) { die('image create failed'); }，可快速定位 imagecreatetruecolor() 因内存不足或参数非法而返回 false 的情况。
第四步：调用 imagedestroy($im) 必须放在 imagepng() 之后，提前销毁会导致输出空内容。
验证 Session 是否正常写入（仅限需校验的场景）
如果验证码用于表单提交校验（如登录页），且后端用 $_SESSION['code'] 存储真实值，则 Session 初始化失败会导致前端显示图片但后端永远校验失败——此时图片本身可能正常，但用户感知为“不显示”（因输对也报错）。
在验证码脚本开头加入 session_start(); $_SESSION['test'] = 'ok';，另建一个测试页读取 dump($_SESSION['test']);，若输出 null，说明 Session 未生效。
检查 php.ini 中 session.save_path 指向目录是否存在且 Web 进程有写权限；确认 session.auto_start = 0（需手动调用 session_start()）；Linux 下常见问题是 /var/lib/php/sessions 目录属主不是 www-data，导致 session 文件无法创建。
