qrcode.js 前端下载：将生成的二维码保存为 PNG 图片

图示：纯前端调用 qrcode.js 生成二维码并导出为 PNG 图像文件的核心模型

一、qrcode.js 的 DOM 渲染机制与节点结构

要想稳妥地提取二维码图像，必须先了解 qrcode.js（常见为 davidshimjs/qrcodejs）在页面 DOM 树中到底放置了什么。很多开发者尝试通过常规选择器下载图片时失败，往往是因为误判了内部生成的节点结构。

当执行 new QRCode(container, options) 时，库为了兼顾不同历史版本浏览器的兼容性，会在传入的宿主容器（通常是一个 div）中同时生成两个并列的子节点：

• <canvas> 元素：现代浏览器中的首要渲染载体。算法完成矩阵编码后，会直接在这个画布上下文上绘制黑白模块。它的位图数据始终是立即可用的。
• <img> 元素：为了支持手机端用户长按保存或者旧版浏览器，库在画布绘制完成后，会自动将画布导出为 Base64 字符串并写入该图片的 src 属性中。在部分旧环境下，<canvas> 可能会被设置 style="display:none"，而仅显示 <img>。

图 1：qrcode.js 渲染机制与 DOM 元素结构解析

这意味着提取二维码图源存在两条技术路径：路径 A（首选）直接定位容器内的 <canvas> 元素并调用其原生 API；路径 B读取 <img> 标签的 src 属性。路径 A 的优势在于 Canvas 的内存绘制是同步完成的，不需要等待浏览器重排解析图片 DOM，因此在触发批量或即时下载时稳定性最高。

二、保存为 PNG 图片的核心实现步骤

明确了 DOM 结构后，实现点击下载只需按照标准的浏览器端文件落地时序进行：从实例构建、数据提取、链接封装到触发清理。

图 2：前端保存与下载二维码的完整执行时序与步骤

步骤 1：准备宿主容器并生成二维码实例

在 HTML 中定义一个挂载点容器，并在 JavaScript 中实例化二维码。需要注意的是，new QRCode 传入的 width 和 height 参数直接决定了生成的底图画布像素尺寸：

<!-- HTML 宿主容器与操作按钮 -->
<div id="qrcode-box"></div>
<button id="btn-download">下载 PNG 二维码</button>

<script>
  // 实例化二维码
  const qrContainer = document.getElementById('qrcode-box');
  const qrInstance = new QRCode(qrContainer, {
    text: 'https://example.com/target-page',
    width: 300,
    height: 300,
    colorDark: '#000000',
    colorLight: '#ffffff',
    correctLevel: QRCode.CorrectLevel.H
  });
</script>

步骤 2：提取图源并派发下载链接

为按钮绑定点击事件。在事件回调中，先在容器内部查找 canvas 元素。为了避免极端兼容环境下未渲染 Canvas，代码应具备自动降级至 img.src 的兜底能力：

function downloadQRCode(containerId, filename = 'qrcode.png') {
  const container = document.getElementById(containerId);
  if (!container) {
    console.error('未找到二维码容器节点');
    return;
  }

  let imgUrl = '';
  const canvas = container.querySelector('canvas');

  if (canvas) {
    // 优先从 Canvas 获取 PNG 格式 DataURL
    imgUrl = canvas.toDataURL('image/png');
  } else {
    // 降级方案：从生成的 img 标签读取 base64 数据
    const img = container.querySelector('img');
    if (img && img.src) {
      imgUrl = img.src;
    }
  }

  if (!imgUrl) {
    console.warn('二维码图像尚未生成完毕或数据为空');
    return;
  }

  // 创建虚拟 a 标签触发文件保存
  const link = document.createElement('a');
  link.href = imgUrl;
  link.download = filename;

  // 兼容 Firefox：必须将节点临时加入 DOM 树后点击才有效
  document.body.appendChild(link);
  link.click();
  document.body.removeChild(link);
}

document.getElementById('btn-download').addEventListener('click', () => {
  downloadQRCode('qrcode-box', 'my-qrcode.png');
});

三、DataURL 直接绑定 vs Blob URL 方案对比

在上述实现中，我们直接将 canvas.toDataURL() 返回的长字符串赋给了链接。在常规的二维码场景下（通常尺寸在 200px 至 600px 之间），Base64 字符串长度一般在 10KB 至 50KB 左右，这种直接绑定的方式轻快、无延迟。但如果你的应用需要支持超高分辨率（例如生成 2000px 以上用于印刷的海报），或者遵循严格的前端工程内存规范，转换为 Blob URL 则是更为稳健的选择。

图 3：DataURL 与 Blob URL 下载方案全维度对比

两种方案的关键特性对比

使用 Blob URL 进行导出的健壮代码

如果选择使用 Blob 方案，可以通过 HTMLCanvasElement.toBlob() 实现异步导出：

function downloadQRCodeViaBlob(containerId, filename = 'qrcode.png') {
  const container = document.getElementById(containerId);
  const canvas = container ? container.querySelector('canvas') : null;

  if (!canvas) {
    console.error('未找到画布节点');
    return;
  }

  canvas.toBlob((blob) => {
    if (!blob) {
      console.error('生成 Blob 失败');
      return;
    }

    const blobUrl = URL.createObjectURL(blob);
    const link = document.createElement('a');
    link.href = blobUrl;
    link.download = filename;

    document.body.appendChild(link);
    link.click();
    document.body.removeChild(link);

    // 下载指令发起后，延时释放 Blob URL 对象所占用的内存
    setTimeout(() => {
      URL.revokeObjectURL(blobUrl);
    }, 200);
  }, 'image/png');
}

四、核心要点与排查避坑指南

在实际生产环境中，将二维码导出为图片可能遇到清晰度不足、下载内容空白或移动端不响应等具体问题。以下梳理四个最关键的技术细节和解决方法。

图 4：qrcode.js 前端保存核心要点与排查避坑总结

1. 导出分辨率与高清度保证（物理像素 vs 样式像素）

很多开发者发现，导出的 PNG 二维码在手机屏幕或打印件上显得发虚或有锯齿，但页面上看起来却很正常。这种现象的原因在于混淆了 Canvas 画布绘制的物理像素和 CSS 显示尺寸。

如果在 new QRCode 时配置了 width: 120, height: 120，那么生成的画布本身就只有 120×120 个物理像素。导出后的 PNG 也只有这个分辨率。如果希望导出的图片在高分屏或打印中保持极高清晰度，正确的做法是以大尺寸实例化二维码，并通过 CSS 样式缩小展示：

/* CSS 控制页面显示尺寸 */
#qrcode-box {
  width: 160px;
  height: 160px;
}
#qrcode-box canvas,
#qrcode-box img {
  width: 100%;
  height: 100%;
}

/* JS 生成高清 600px 物理位图 */
new QRCode(document.getElementById('qrcode-box'), {
  text: 'https://example.com',
  width: 600,   // 导出时具备完整的 600×600 像素，清晰锐利
  height: 600,
  correctLevel: QRCode.CorrectLevel.H
});

2. 时序问题导致的空白图片

如果你在调用 new QRCode(...) 后立刻同步触发下载，有时下载出来的文件可能是一张全透明或全白的图片。这是因为：

1. 如果你的代码从 <img> 标签提取 src，库从 Canvas 转 Base64 并赋值到 DOM 属性的过程存在微小的时差。在实例化完成的那一行之后立即读取 img.src，很可能是空值。
2. 如果容器位于 display: none 的弹窗或隐藏 Tab 中，部分浏览器可能延迟渲染 Canvas。

应对方案：若必须从图片标签提取，可使用 setTimeout(..., 50) 延迟执行，或者优先直接读取 container.querySelector('canvas')；在有弹窗的场景中，确保在容器变为可见后再执行生成逻辑。

3. 移动端浏览器（尤其是 iOS Safari）的行为适配

在 PC 端，<a download="..."> 属性是标准的文件下载触发方式。但在移动端（尤其是 iOS 系统的 Safari 或微信内置浏览器），出于系统沙箱和安全策略，程序直接调用 link.click() 往往不会弹出系统“保存到相册”的动作，而是直接在新标签页中打开图片原图，或者直接被拦截无反应。

4. 二维码动态更新与实例清理

当需要根据用户输入的文字动态刷新二维码时，切勿重复执行 new QRCode(...)，否则会在宿主容器内不断追加新的 Canvas 和 Image 节点，导致下载方法获取到的始终是第一个旧二维码。

正确的复用方式是使用实例自带的 clear() 与 makeCode() 方法：

// 创建单例
const qr = new QRCode(document.getElementById('qrcode-box'), {
  width: 300,
  height: 300
});

// 更新内容时调用 makeCode
function refreshQR(newContent) {
  qr.clear();             // 清除上一次的渲染数据
  qr.makeCode(newContent); // 重新在原节点上绘制新二维码
}

五、总结

使用 qrcode.js 在纯前端保存 PNG 图片，本质上是一次标准的前端位图导出与文件派发过程。在技术选型与实现上，牢记以下三个核心准则：

• 定位数据源：首选容器内的 <canvas> 原生节点，调用 toDataURL('image/png') 获得最即时、纯粹的像素数据；
• 触发下载：动态创建 <a download="name.png"> 并挂载到 document.body，模拟点击后及时卸载，确保兼容包括 Firefox 在内的主流桌面浏览器；
• 清晰度分层：以目标打印或保存所需的高分辨率参数（如 500px - 800px）初始化实例，而在 CSS 层面限制视口宽度，兼顾界面布局美观与导出文件的锐利度。