qrcode.js 生成的二维码模糊怎么办？调整 Canvas 尺寸解决

前端开发 · 渲染调优

在使用 qrcode.js 生成网页二维码时，许多开发者会发现二维码在手机端、Retina 视网膜屏或弹窗放大时边缘发灰发虚。这个问题的根源在于 Canvas 内部位图缓冲区的物理像素尺寸（width / height 属性）与屏幕物理像素密度（devicePixelRatio）失配。解决的核心路径非常简单明了：将 qrcode.js 生成的 Canvas 物理像素尺寸按设备像素比成倍放大，再通过 CSS 样式将其显示尺寸强制约束回预期的界面尺寸。

一、为什么 qrcode.js 生成的二维码会发虚模糊？

为了彻底解决模糊问题，首先需要理解浏览器渲染 Canvas 元素时的两套像素体系：逻辑像素（CSS 像素）与设备物理像素（Device Pixels）。

现代智能手机、高分辨率笔记本电脑（如 MacBook Retina 屏）和 2K/4K 显示器的物理像素密度极高。浏览器通过全局属性 window.devicePixelRatio（简称 DPR）来表达这种倍率关系：

// 设备像素比公式
设备像素比 (DPR) = 屏幕物理像素点数 / 浏览器 CSS 逻辑像素点数

常见普通显示器的 DPR 为 1；而 iPhone 等移动设备以及 Retina 屏幕的 DPR 通常为 2 或 3。这意味着在 DPR 为 2 的屏幕上，一个宽 150px 的 CSS 容器在屏幕上实际占据了 300 个物理发光子像素。

然而，经典库 qrcode.js（包括社区常见的各类派生包）在初始化时，直接将配置项中的 width 和 height 赋给了 Canvas 的 DOM 属性：

// 常见默认配置（未适配高分屏）
var qrcode = new QRCode(document.getElementById("qrcode"), {
  text: "https://example.com",
  width: 150,
  height: 150
});

上述代码会创建一个 <canvas width="150" height="150">。此时，Canvas 内部只有 150×150 像素的位图缓冲区。当浏览器把它渲染到占据 300×300 物理像素的屏幕区域时，不得不进行双线性插值（Bilinear Interpolation）缩放。这种平滑插值会把原本黑白分明的几何方块边缘抹上不同透明度的灰色过渡像素，造成肉眼可见的“发虚”、“毛边”和“对比度下降”。

二、核心解决思路：分离 Canvas 绘制缓冲区与 CSS 视觉尺寸

解决模糊的本质，不是去改变二维码的编码算法，而是让 Canvas 画布的物理缓冲区像素与屏幕的物理发光点 1:1 精确对齐。

HTML5 <canvas> 拥有两个截然不同的尺寸属性：

尺寸类型	表现形式	决定内容	修改方式
物理缓冲尺寸 (Drawing Buffer)	Canvas 元素的 width 与 height 属性（无单位）	画布内存位图的分辨率，决定细节精细度	JavaScript 动态设置或 qrcode.js 初始化配置参数
CSS 显示尺寸 (Display Size)	style="width: ...px; height: ...px;" 或外部 CSS	页面布局排版时占用的实际空间	CSS 样式表或内联 style

三、具体操作步骤与完整代码实现

按照规范的工程实践，解决 qrcode.js 模糊只需要以下四个标准步骤：

步骤 1：获取设备像素比（DPR）

从浏览器窗口读取 window.devicePixelRatio。为了保障在无头环境或旧版内核中的鲁棒性，添加回退值 1。为了兼顾打印机或极端高分屏，通常限制最大倍率为 3 或 4，避免超出手机显存限制：

const dpr = Math.min(window.devicePixelRatio || 1, 4);

步骤 2：计算实际渲染所需的物理像素尺寸

假设 UI 设计稿要求二维码在页面上的显示尺寸为 160px × 160px：

const targetDisplaySize = 160; // CSS 目标像素
const physicalRenderSize = targetDisplaySize * dpr; // 物理位图缓冲大小（如 320 或 480）

步骤 3：将放大后的尺寸传递给 QRCode 构造函数

在初始化 qrcode.js 时，传入计算后的 physicalRenderSize。这样库底层生成的 Canvas 将具备足够精细的黑白网格数据：

const qrcode = new QRCode(document.getElementById("qrcode-box"), {
  text: "https://example.com/checkout/order-9821",
  width: physicalRenderSize,
  height: physicalRenderSize,
  colorDark: "#30363C",
  colorLight: "#FFFFFF",
  correctLevel: QRCode.CorrectLevel.H
});

步骤 4：通过 CSS 锁死子元素的视觉呈现尺寸

由于传入了高倍率尺寸，生成的 Canvas 会默认以 320px 甚至更大尺寸撑开父容器。必须在 CSS 中显式覆盖其样式尺寸，将其强制收敛至 160px：

/* 统一约束容器及其内部 canvas、img */
.qr-code-wrapper {
  width: 160px;
  height: 160px;
  position: relative;
}

.qr-code-wrapper canvas,
.qr-code-wrapper img {
  width: 160px !important;
  height: 160px !important;
  display: block;
}

完整可运行的前端封装示例

下面是一个开箱即用、具备自动高分屏识别与容错处理的完整 HTML / JavaScript 组件示例：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>高清晰度 QRCode 渲染示例</title>
  <script src="https://cdn.jsdelivr.net/npm/qrcodejs@1.0.0/qrcode.min.js"></script>
  <style>
    .qr-card {
      display: inline-block;
      padding: 16px;
      background: #FFFFFF;
      border: 1px solid #DEDAD1;
      border-radius: 8px;
    }
    .hd-qrcode {
      width: 160px;
      height: 160px;
    }
    /* 核心样式：强制约束内部生成的元素尺寸 */
    .hd-qrcode canvas,
    .hd-qrcode img {
      width: 100% !important;
      height: 100% !important;
      display: block;
    }
  </style>
</head>
<body>

  <div class="qr-card">
    <div id="my-hd-qrcode" class="hd-qrcode"></div>
  </div>

  <script>
    function renderSharpQRCode(containerId, text, cssSize) {
      const container = document.getElementById(containerId);
      if (!container) return;

      // 1. 获取屏幕 DPR，保证高分屏对齐
      const dpr = Math.max(window.devicePixelRatio || 1, 2);

      // 2. 清空既有内容（避免重复重绘累加）
      container.innerHTML = "";

      // 3. 按 DPR 物理放大尺寸进行绘制
      const renderSize = Math.round(cssSize * dpr);

      new QRCode(container, {
        text: text,
        width: renderSize,
        height: renderSize,
        colorDark: "#30363C",
        colorLight: "#FFFFFF",
        correctLevel: QRCode.CorrectLevel.H
      });
    }

    // 执行渲染：视觉呈现 160px
    renderSharpQRCode("my-hd-qrcode", "https://example.com", 160);
  </script>
</body>
</html>

四、深入细节：qrcode.js 的 DOM 特性与双节点陷阱

在实际项目中，如果不了解 qrcode.js 的内部工作方式，往往会踩入一些隐藏陷阱：

1. 为什么必须同时给 canvas 和 img 设置样式？

阅读 qrcode.js 源码可以发现，其内部在完成 Canvas 绘制后，紧接着执行了一步：

this._elImage.src = this._elCanvas.toDataURL("image/png");

该库会在容器中同时插入 <canvas> 与 <img>。在支持 Canvas 的桌面端浏览器上，<canvas> 处于可见状态；而在微信内置浏览器、iOS Safari 或部分移动端 WebView 中，用户长按保存图片或调用原生扫码识别时，浏览器读取的是 <img> 标签。

如果 CSS 中只写了 #qrcode canvas { width: 160px; }，生成的 <img> 依然保持 320px 物理尺寸，在移动端会导致布局严重变形跑位，或者在不同内核切换显隐状态时再次模糊。因此，样式规则务必同时覆盖 canvas 和 img。

2. 动态弹窗（Modal）中的零尺寸报错与模糊问题

在 Bootstrap、Element UI 或 Ant Design 等弹窗中生成二维码时，如果在 Modal 尚未完全展开（处于 display: none 状态）时初始化 qrcode.js，Canvas 无法正确获取父级盒模型，可能导致绘图尺寸异常或空白。

五、常见边界场景与进阶排查方案

场景 1：移动端长按保存与印刷级导出（DPI 提升）

如果生成的二维码不仅用于屏幕展示，还需要供用户长按“保存到手机相册”后打印出来（例如会议签到码、实体桌贴），那么即使在屏幕上看起来清晰的 320px 二维码，打印在纸质材料上依然会出现马赛克。

纸质印刷品通常要求 300 DPI。针对该场景，建议直接将 Canvas 渲染尺寸固定提升至 800px ~ 1200px，而 CSS 显示仍限定在页面所需的尺寸（如 180px）。此时长按保存导出的 Base64 图片便是超清版本，无论是手机相册二次放大还是线下高精度喷绘打印，都能保持无损清晰度。

场景 2：CSS image-rendering 属性的辅助增强

对于极小尺寸的二维码图标（例如 64px 导航小图标），浏览器的抗锯齿插值可能让黑白格子之间的分界稍微发软。在扩大 Canvas 尺寸之余，可以配合 CSS 图像渲染属性：

.hd-qrcode canvas,
.hd-qrcode img {
  image-rendering: -webkit-optimize-contrast; /* Safari / 早期内核 */
  image-rendering: pixelated;                 /* 现代标准：像素化近邻取样 */
}

该属性会指示浏览器在缩放位图时采用最近邻采样算法（Nearest Neighbor），强制消除柔化灰边，保持绝对纯黑与纯白的几何方块对比。

场景 3：SVG 矢量模式对比与选型建议

部分 qrcode.js 的增强版本（或 EasyQRCodeJS、qrcodejs2）支持直接输出 SVG 格式（useSVG: true）。

SVG 模式由 <path> 或 <rect> 矢量标签组成，天然具备任意缩放不失真的优势。然而在微信生态与移动端，SVG 标签无法直接被微信长按识别或保存至相册。因此：

• 优先使用 Canvas 缓冲区放大 + CSS 缩放方案：兼容性最佳，既保证高分屏极致锐利，又原生支持移动端长按保存与扫码。
• 大屏展示或纯 Web 交互：若无需长按保存功能，可直接选用 SVG 模式，彻底免去计算 DPR 的逻辑。

六、验收检查清单

在完成 Canvas 尺寸调整后，可以通过以下几个步骤快速确认问题已经彻底解决：

• 审查 DOM 属性：打开 Chrome / Safari 开发者工具，检查 <canvas> 标签的 width 属性值是否为实际 CSS 宽度的 2 倍或 3 倍（例如 CSS 宽 160px，标签属性为 320 或 480）。
• 检查计算样式：检查 <canvas> 和 <img> 的 Computed Style，确认 width 与 height 是否严格锁死在目标像素，未发生布局溢出。
• 微观边缘检查：使用浏览器缩放至 200% 或在 Retina 屏幕上近距离观察二维码边缘，确认黑白交界线干净利落，无任何发灰、透明渐变插值。
• 移动端长按测试：在真机微信或手机浏览器中打开页面，长按识别二维码，确保识别灵敏无延迟，保存到本地相册后放大检查画面依旧清晰。