php 的 imagepng() 函数是同步阻塞调用，执行完毕即表示文件已完整写入磁盘；只需检查其返回值是否为 true，无需轮询文件系统，可彻底避免超时、死循环及服务器崩溃风险。
php 的 imagepng() 函数是同步阻塞调用，执行完毕即表示文件已完整写入磁盘；只需检查其返回值是否为 true，无需轮询文件系统，可彻底避免超时、死循环及服务器崩溃风险。
在图像处理流程中，尤其是对 QR 码等生成后需立即读取或分发的场景，常误以为 imagepng($image, $filePath) 可能“异步返回”或“未完成写入”，进而采用轮询 file_exists() 的方式等待——这不仅逻辑错误，还会引发严重问题：无限循环、CPU 占用飙升、请求超时、甚至 Apache/Nginx 工作进程崩溃。
事实上，imagepng()（以及 imagejpeg()、imagegif() 等 GD 写入函数）是完全同步且原子性完成的：它会将整个 PNG 数据编码、压缩并完整写入指定文件路径的磁盘文件中，只有当操作系统确认写入成功（包括缓冲区刷盘，取决于底层 fwrite() 和 fflush() 行为），该函数才返回 true；若失败（如磁盘满、权限不足、路径不可写），则返回 false。
因此，正确的做法是直接校验 imagepng() 的返回值：
$filePath = "/qrCodes/qrcode{$text}.png";
if (imagepng($image, $filePath) === true) {
return $filePath;
} else {
throw new RuntimeException("Failed to save QR code image to {$filePath}");
}
⚠️ 注意事项：
- 不要使用 while 循环检测文件是否存在：file_exists() 轮询既无必要，又极易因条件竞争或 I/O 延迟导致假阴性，还可能因未设最大重试次数而阻塞进程；
- 确保目录可写且存在：调用前应通过 is_writable(dirname($filePath)) 或 mkdir(..., 0755, true) 预检路径，避免 imagepng() 静默失败；
- 及时释放资源：处理完成后调用 imagedestroy($image) 释放 GD 资源，防止内存泄漏；
- 错误报告需开启：开发阶段建议启用 error_reporting(E_ALL) 和 display_errors=On，以便捕获 GD 扩展警告（如字体加载失败、图像尺寸异常等）。
综上，移除所有轮询逻辑，信任 imagepng() 的同步语义，并辅以基础路径与权限校验，即可构建健壮、高效、符合 PHP GD 最佳实践的图像写入流程。
