PHP生成二维码教程：endroid/qr-code使用详解

本文深入解析了使用 PHP 库 endroid/qr-code 生成二维码的实战要点，重点指出版本选择的关键影响：v3.5.2 稳定兼容 PHP 7.2+、API 简洁、开箱即用，而 v4+ 虽功能增强却移除了 save() 和 get() 等便捷方法，要求显式配置渲染器（如 GD）、手动处理响应头与二进制输出，并强制 PHP 8.0+，稍有疏忽便导致“图不显示”或“UnsupportedRendererException”等典型问题；文章还手把手指导安装命令、GD 扩展检查、正确输出到浏览器（需 header + render）、安全保存文件及避免 HTML 嵌入误区，助你避开踩坑、快速落地可用的二维码生成功能。

直接用 endroid/qr-code 生成二维码没问题，但 v4+ 版本移除了内置响应输出和文件保存的快捷方法，不注意会卡在“生成了但看不到图”或“报错找不到 save()”。

安装时必须指定兼容版本或补全依赖

v4.x（当前默认）要求 PHP ≥ 8.0，且不再自带 imagick 或 gd 的自动 fallback。如果服务器只有 GD 扩展，又没显式配置渲染器，会抛出 UnsupportedRendererException。

• 推荐直接装 v3.5.2（稳定、PHP 7.2+ 兼容、API 简单）：composer require endroid/qr-code:^3.5
• 若坚持用 v4+，需额外装渲染器，例如：composer require endroid/qr-code endroid/qrcode-bundle（仅 Symfony）或手动引入 endroid/qr-code-renderer-gd
• 检查 GD 是否启用：php -m | grep gd；若无，需开启 extension=gd 并重启 PHP

QrCode::create() 后不能直接 echo，得先渲染成二进制流

v3 中 get() 返回 PNG 二进制数据，v4 中改用 render()，且返回值类型变了——它返回的是 string（原始 PNG 数据），不是 Response 对象，更不是可直接输出的 HTML 标签。

• 正确输出到浏览器：

  header('Content-Type: image/png');
  echo $qrCode->render();

• 保存为文件（v3/v4 均可用）：$qrCode->writeFile('qrcode.png'); —— 注意路径需有写权限
• 嵌入 HTML 的常见错误：直接 会失败，因为 render() 返回的是二进制，不是 base64 或 URL；应先存文件或用 data URI：data:image/png;base64,render()); ?>

中文内容乱码？默认不支持 UTF-8 文本直接编码

endroid/qr-code 底层调用的是 QR code 标准编码（ISO-8859-1），直接传中文字符串会导致解码失败或显示方块。它不自动转码，也不检测字符集。

• 安全做法：用 urlencode() 包裹中文内容，再生成：QrCode::create(urlencode('你好世界'))，扫码后需前端 decodeURIComponent()
• 更通用方案：改用 BYTE 模式并手动指定 ECI（Extended Channel Interpretation），但 v3 不支持，v4 需配合 setEncoding('UTF-8')（仅部分渲染器生效，GD 不支持）
• 简单绕过：把中文转成短链接再编码，避免编码问题本身

最易被忽略的是：v4 默认不带 writeFile() 方法，很多人照着旧文档写会报 Call to undefined method；而 v3 的 get() 在 v4 已废弃。版本混用是第一大坑。

到这里，我们也就讲完了《PHP生成二维码教程：endroid/qr-code使用详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！