Vue 和 React 项目中集成 qrcode.js 的注意事项

架构概览：现代组件化框架与底层原生 DOM 绘图库的桥接模型

一、DOM 挂载时机与容器引用控制

qrcode.js 的初始化构造函数 new QRCode(targetDomElement, options) 要求第一个参数必须是一个真实存在于当前文档树中的 HTML 元素（通常为 <div>）。现代框架在执行组件逻辑时，界面元素并不是瞬间出现在文档中的，而是经历虚拟 DOM 计算、构建和真实 DOM 提交（Commit）的过程。

1. 为什么在 setup 根作用域或函数组件体内直接调用会报错

初学者最容易犯的错误是在 Vue 3 的 <script setup> 顶级执行上下文，或者在 React 函数组件主体代码中直接执行 new QRCode(qrRef.value, ...)。此时虚拟 DOM 尚未完成首轮真实渲染，qrRef.value 或 ref.current 仍是 null 或 undefined。qrcode.js 内部执行到 targetElement.appendChild(...) 时，会立即抛出 TypeError: Cannot read properties of null (reading 'appendChild') 导致页面崩溃。

图 1: Vue 与 React 生命周期挂载时序与安全初始化区间

2. Vue 3 中的正确集成模式

在 Vue 3 中，必须将初始化逻辑延迟至 onMounted 钩子中执行。如果二维码所在容器被包裹在 v-if 条件块、弹窗组件（如 Element Plus 的 el-dialog 或 Ant Design Vue 的 Modal）中，由于对话框的 DOM 结构是在打开动作触发后异步渲染的，还需要结合 nextTick 才能安全获取 DOM 元素。

<template>
  <div class="qr-wrapper">
    <!-- 声明模板引用容器 -->
    <div ref="qrContainerRef" class="qrcode-box"></div>
  </div>
</template>

<script setup>
import { ref, onMounted, nextTick, shallowRef } from 'vue';
import QRCode from 'qrcodejs2-fixes'; // 或修复版 qrcode.js

const qrContainerRef = ref(null);
// 保持原生实例的浅层或普通引用，避免被 reactive 深度代理
const qrInstance = shallowRef(null);

const initQRCode = () => {
  if (!qrContainerRef.value) return;
  qrInstance.value = new QRCode(qrContainerRef.value, {
    text: 'https://example.com/checkout',
    width: 200,
    height: 200,
    colorDark: '#000000',
    colorLight: '#ffffff',
    correctLevel: QRCode.CorrectLevel.H,
  });
};

onMounted(() => {
  // 确保初次渲染及微任务队列完成
  nextTick(() => {
    initQRCode();
  });
});
</script>

3. React 中的正确集成模式

在 React 函数组件中，应使用 useRef 创建对 DOM 容器的持久化引用，并在 useEffect 钩子函数中执行实例化操作。

import React, { useEffect, useRef } from 'react';
import QRCode from 'qrcodejs2-fixes';

export const QRCodeCard = ({ text }) => {
  const containerRef = useRef(null);
  const qrInstanceRef = useRef(null); // 持久化实例，不触发额外重新渲染

  useEffect(() => {
    if (!containerRef.current) return;

    // 初次挂载时创建实例
    if (!qrInstanceRef.current) {
      qrInstanceRef.current = new QRCode(containerRef.current, {
        text: text,
        width: 180,
        height: 180,
        colorDark: '#1E293B',
        colorLight: '#FFFFFF',
      });
    }

    // 组件卸载时释放引用与清理 DOM
    return () => {
      if (containerRef.current) {
        containerRef.current.innerHTML = '';
      }
      qrInstanceRef.current = null;
    };
  }, []); // 仅在挂载和卸载时触发

  return <div ref={containerRef} className="qrcode-container" />;
};

二、动态更新机制与 DOM 节点重复堆积排查

业务场景中二维码的内容往往是动态变化的，例如订单状态轮询刷新、切换支付方式或重新生成校验链接。这是集成 qrcode.js 时出现频率最高的逻辑缺陷。

图 2: 数据动态变更时的 DOM 节点处理路径对比

1. 为什么不能在监听器中直接反复执行 new QRCode

当监听的数据（如 Vue 的 watch(props.url) 或 React 的 useEffect(..., [text])）变化时，如果每次都重新调用 new QRCode(container, newUrl)，qrcode.js 会无条件地直接向目标 DOM 容器中调用 appendChild 追加一个新的 <canvas> 或 <img>。结果就是页面上出现排成一列或堆叠在一起的多个二维码。

2. 两种稳妥的更新策略

• 策略一：复用现有实例调用 makeCode()（推荐最佳实践）
  qrcode.js 内部封装了平滑更新方法。只要实例已被创建，当文本发生改变时，直接调用 qrInstance.makeCode(newText) 即可。此方法直接在原有画布上重新计算并重绘矩阵，不会产生任何多余的 DOM 节点插入与销毁动作，性能最为平稳。
• 策略二：重新实例化前手动清空容器
  如果业务不仅需要改变二维码内容，还需要动态改变二维码的宽高配置、纠错级别或前后景色，由于 makeCode() 仅支持更新文本内容，此时必须重新实例化。但在执行 new QRCode() 之前，必须先显式清空容器内容：container.innerHTML = ''。

三、现代构建工具与服务端渲染 (SSR) 兼容配置

qrcode.js 诞生年代较早，当时的前端生态普遍采用全局脚本或简单的 AMD/CMD 规范，因此在现代前端工程体系中直接引入容易面临模块导出和同构执行两类问题。

图 3: 构建打包与服务端渲染 (SSR) 环境下的模块兼容架构

1. 构建工具对原生模块的解析兼容

原版的 davidshimjs/qrcodejs 源码是通过立即执行函数将 QRCode 挂载到 window 上，并没有编写标准的 ES Module（export default）。在 Vite 或开启严格模式的 Webpack 5 项目中直接执行 import QRCode from 'qrcodejs' 时，构建工具会提示无法找到默认导出（Requested module does not provide an export named 'default'）。

针对这一问题，有两种可行的工程化方案：

1. 选用已修复模块化导出的衍生包： 如社区长期维护的 qrcodejs2-fixes，其完整补充了标准 ES Module 导出规范与 TypeScript 类型定义。
2. 现代通用库选型： 若项目处于新起步阶段，更推荐引入 qrcode（即 node-qrcode），该库不仅支持现代模块系统，还同时提供 QRCode.toCanvas、QRCode.toDataURL 等丰富的 Promise/异步接口，对现代框架更加契合。

2. Nuxt 与 Next.js 中的 SSR 隔离防护

在 Nuxt 3 或 Next.js 等服务端渲染框架中，组件代码在服务端（Node.js 环境）预渲染执行时，宿主环境中根本不存在 window、document 或 HTMLCanvasElement。如果将 qrcode.js 放在文件顶部静态导入并立即求值，服务进程会直接抛出 ReferenceError: document is not defined。

必须采取严格的环境隔离措施：

• 在组件模板外层使用 <ClientOnly>（Nuxt）或 dynamic(() => import(...), { ssr: false })（Next.js）进行包装，确保代码仅在客户端水合后执行。
• 在生命周期内使用动态 import() 按需载入：const QRCode = (await import('qrcodejs2-fixes')).default;。

四、渲染格式、移动端长按识别与分辨率模糊适配

在移动端网页开发中，二维码不仅需要供外置手机摄像头扫描，还经常需要支持用户长按屏幕弹出系统菜单进行“识别图中的二维码”或“保存图片”。

1. Canvas 与 Image 渲染模式对长按识别的影响

qrcode.js 默认优先在容器中绘制 <canvas>，随后在底层尝试将其导出为 Base64 编码并追加 <img> 标签。在微信内置浏览器及主流移动端浏览器中，用户长按网页元素触发系统扫码菜单的前提是：被按压的元素必须是合法的 <img> 标签。

如果容器内的 <canvas> 遮挡在 <img> 上层，或者由于某些样式设置导致图片层未成功渲染，长按将没有任何反应。可以通过 CSS 检查确保容器内的 img 元素具有明确的层级和显示属性：

.qrcode-box img {
  display: block;
  width: 100%;
  height: 100%;
  pointer-events: auto; /* 保证触控事件被图片原生捕获 */
}

.qrcode-box canvas {
  display: none; /* 移动端可隐藏纯画布，仅保留已生成的 img */
}

2. 高清屏下的抗锯齿与模糊失真防护

许多开发者为了适配自适应布局，直接设置固定像素参数（如 width: 100）初始化二维码，随后通过 CSS width: 100% 将其强行放大到视口宽度。这种操作本质上是对低分辨率位图进行拉伸插值，会导致黑白矩阵边缘模糊、过渡发虚，严重降低扫码器的解码成功率。

推荐的适配标准是：按照设备像素比（window.devicePixelRatio）或目标显示宽度的 2 至 3 倍生成二维码像素尺寸，再通过 CSS 将其约束在视觉所需的物理尺寸内。

五、工程化自查清单与核心决策图谱

在 Vue 与 React 项目交付生产前，可以对照以下五维核心自查图谱，快速复核二维码组件的健壮性：

图 4: Vue 与 React 项目集成 qrcode.js 五维核心自查与决策图谱

• 挂载时机检查： 初始化代码必须处于 onMounted（Vue）或 useEffect（React）中，严禁在渲染前上下文中过早引用容器。对于受 v-if 控制的弹窗，务必配合 nextTick 执行。
• 更新机制检查： 内容发生变更时，优先调用 makeCode() 原位更新；若重新实例化，必须前置执行 container.innerHTML = '' 清理。
• 内存回收检查： 在组件销毁钩子（onBeforeUnmount 或 React 的 Effect 清理函数）中主动清空 DOM 容器并释放实例变量引用，规避 SPA 路由反复切换造成的内存泄漏。
• 服务端渲染安全： 针对同构 SSR 框架，使用动态导入或客户端专用组件进行包裹，严防 Node.js 服务端出现 document is not defined。
• 长按与高清适配： 移动端必须保留 <img> 节点以支持系统级扫码交互，按设备像素比配置生成尺寸，确保各类移动设备上的高识别率。