GD库未启用或缺失PNG/JPEG支持会导致imagepng()等函数报错；需先用extension_loaded('gd')和function_exists()确认状态，再检查依赖、字体路径、输出缓冲及文件权限。
GD库未启用或缺失图像写入能力
PHP生成二维码依赖GD库的imagepng()、imagejpeg()等函数，如果GD扩展未加载，或编译时禁用了PNG/JPEG支持，调用会静默失败或抛出Call to undefined function imagepng()错误。
执行以下代码确认GD状态和关键功能是否可用：
var_dump([
'gd_loaded' => extension_loaded('gd'),
'png_support' => function_exists('imagepng'),
'jpeg_support' => function_exists('imagejpeg'),
'freetype_support' => function_exists('imagettftext'),
]);
常见问题包括：
- Ubuntu/Debian 系统只装了
php-gd，但没装php-freetype（旧版）或libfreetype6-dev（编译依赖），导致imagettftext()不可用，带文字的二维码直接报错 - Alpine Linux 默认 GD 不含 FreeType，需显式安装：
apk add php7-gd php7-freetype - Windows 下 php.ini 中启用了
extension=php_gd2.dll，但 DLL 依赖的freetype.dll或libpng16.dll缺失，Apache 启动时报错或图像输出为空
FreeType 字体路径或权限不合法导致文字渲染失败
很多二维码库（如 Endroid\QrCode）默认尝试用系统字体渲染 label 或 logo 文字。若传入的 .ttf 路径不存在、不可读，或字体文件本身损坏，imagettftext() 会返回 false，但多数库不会中断流程——结果是图片生成成功，但文字区域空白或乱码，用户误以为“图片没显示”。
立即学习“PHP免费学习笔记（深入）”；
验证方式：临时禁用文字相关设置，看是否恢复显示：
$qrCode = new QrCode('test');
// 注释掉这行试试
// $qrCode->setLabel('Scan me', 14, '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf');
$qrCode->writeFile('/tmp/test.png');
若此时图片能正常生成并显示，说明问题出在字体环节。排查要点：
-
file_exists()和is_readable()必须同时为true才能安全传给imagettftext() - 不要用 Windows 风格路径（如
C:\Windows\Fonts\arial.ttf）在 Linux 服务器上硬编码 - 避免使用相对路径如
./fonts/arial.ttf—— CLI 和 Web 运行时的当前工作目录不同，极易失效 - 推荐用
__DIR__ . '/assets/DejaVuSans.ttf'并确保该文件随部署一起上传
header() 输出前存在任何输出导致二进制流损坏
当用 header('Content-Type: image/png') + echo $qrCode->writeString() 直接输出图片时，任何前置输出（空格、BOM、var_dump()、警告信息）都会混入 PNG 二进制流，浏览器收到后解析失败，显示为破损图标或一片空白，开发者控制台 Network 标签里看到响应体开头是“Warning: ... in /path/to/file.php on line XPNG”就是典型表现。
必须保证输出前无任何内容，建议做法：
- PHP 文件保存为 UTF-8 无 BOM 格式（编辑器可设，VS Code 默认即符合）
- 所有调试语句（
echo、var_dump、print_r）移除或注释，尤其注意文件末尾有没有空行 - 开启输出缓冲并在 header 前清理：
ob_start(); ob_clean(); header(...); echo ...; ob_end_flush(); - 开发阶段加一句
if (headers_sent($file, $line)) { die("Headers already sent in {$file}:{$line}"); }定位源头
writeFile() 成功但 Web 无法访问生成的图片路径
很多人调用 $qrCode->writeFile('qrcode.png') 后，直接在 HTML 里写 <img src="qrcode.png">，却发现 404。这不是生成失败，而是路径理解偏差。
writeFile() 的参数是**服务器端绝对或相对路径**，不是 URL 路径。例如：
-
$qrCode->writeFile('qrcode.png')→ 写入到当前 PHP 脚本所在目录，但该目录通常不在 Web 可访问范围内（如/var/www/app/src/） -
$qrCode->writeFile($_SERVER['DOCUMENT_ROOT'] . '/uploads/qrcode.png')→ 正确：生成到 Web 可达位置 - 更安全的做法是用
realpath()校验路径：if (!is_writable(dirname($path))) { die('Directory not writable'); }
生成后务必用 file_exists() 和 getimagesize() 验证文件真实存在且是有效图片：
$path = '/var/www/html/uploads/qrcode.png';
if (!file_exists($path) || !getimagesize($path)) {
error_log("QR image invalid or missing: {$path}");
exit;
}
真正容易被忽略的是：GD 支持 PNG 但不等于支持 Alpha 通道导出；某些旧版 GD 在调用 imagealphablending(false) + imagesavealpha(true) 后仍会输出全黑图——这种缺陷只能升级 GD 或换用 Imagick 后端。
