simple qrcode 的 merge 方法必须在调用前设置 format('png')，否则静默失败；logo 必须为 png 格式、路径正确、透明背景，且百分比建议 0.15–0.4。
merge 方法必须配合 format('png') 使用
Simple QrCode 的 merge 方法只支持 PNG 格式输出，调用前没设 format('png') 会静默失败或返回空白内容（尤其在 Blade 中直接输出时）。这不是 bug，是底层 BaconQrCode 对图像合成的硬性限制。
常见错误现象：QrCode::merge('logo.png')->generate('url') 返回乱码或无法识别的 SVG 内容；QrCode::format('svg')->merge(...) 完全忽略 logo。
-
format('png')必须是链式调用的第一个方法（或至少在merge之前） - logo 文件路径必须可读，且推荐用
public_path('logo.png')拼接，避免相对路径歧义 - 如果用 URL 加载 logo（如
merge('https://...', 0.3, true)），需确保服务器能正常发起 HTTP 请求（部分生产环境禁用 cURL 或 fopen URL wrappers）
Logo 尺寸百分比和绝对路径参数容易混淆
merge($path, $percentage, $absolute = false) 的第三个参数控制路径解析逻辑，不是“是否使用绝对路径”，而是“是否跳过 base_path() 自动拼接”。设为 true 时，库会原样使用你传入的字符串作为文件路径 —— 如果你传的是 '/var/www/logo.png'，它就真去读这个路径；如果你传的是 'public/logo.png' 却设了 true，它不会自动补 base_path()，大概率报错 file not found。
更安全的做法：
- 本地 logo：用
public_path('logo.png')得到完整路径，然后merge($fullPath, 0.3)（第三个参数省略，默认 false，但此时路径已是绝对路径，$absolute 实际不起作用） - 远程 logo：明确传
true，且确保 URL 可访问、返回 PNG 类型响应 - 百分比值建议在 0.15–0.4 之间：太小看不清，太大破坏纠错能力，扫码失败率明显上升
Logo 图像本身有格式与透明度要求
即使路径和参数都对，logo 图像若不符合条件，也会导致生成失败或二维码变模糊。Simple QrCode 底层用 GD 处理图像，对输入敏感。
- 必须是 PNG 格式（不支持 JPG、GIF、WebP）；透明背景推荐保留 alpha 通道，否则白色边缘会遮盖二维码模块
- 原始 logo 尺寸不宜过大（建议 ≤ 512×512），GD 在缩放时对超大图处理慢，且可能触发内存限制
- 避免含嵌入 ICC 配置文件的 PNG —— 某些设计软件导出的“高质量 PNG”自带色彩配置，GD 读取时可能崩溃或报
imagecreatefromstring(): Data is not in a recognized format - 调试技巧：先用
getimagesize($path)检查 logo 是否能被 PHP 正常识别，再调用merge
生成后保存或响应输出时注意 header 和二进制安全
带 logo 的二维码本质是 PNG 二进制流，直接 echo 或 Blade 中 {!! !!} 输出时，若前面有空格、BOM 或意外输出，会导致图片损坏（浏览器显示“破损的图像”）。
- 在控制器中生成并返回响应时，务必用
response()->make($binaryData)->header('Content-Type', 'image/png') - 不要在
generate()前后有任何echo、var_dump、调试日志输出 - 保存到磁盘时，确认目录有写权限，且路径末尾带扩展名（如
qrcode.png），否则generate($content, $path)可能写入失败而不报错 - 如果前端需要 base64，别用
base64_encode(QrCode::...->generate())直接套 —— 先确保generate()返回的是真实 PNG 二进制，否则 base64 后仍是乱码
format('png') 是否真的在 merge 之前执行 —— 这两个点不出错时一切顺利，一出错就只能看到空白或报 GD 相关警告，很难联想到根源在这两处。
