Web 端二维码扫描库深度对比：@zxing/library、html5-qrcode、jsqr、qr-scanner 与 qrcode-reader

在现代 Web 应用中，扫码功能已成为常见需求 —— 从登录验证到支付确认，再到信息录入。面对多个开源选项，开发者常困惑于如何选择最适合的库。本文将从核心能力、使用方式、控制粒度和实际代码层面，深入比较五个主流二维码扫描库，帮助你做出明智的技术决策。

🚫 首要提醒：弃用包请勿使用

首先明确一点：qrcode-reader 已被官方弃用。其 npm 页面明确标注 "This package has been deprecated"，GitHub 仓库也处于归档状态。这意味着它不再接收更新、安全修复或兼容性改进。任何新项目都应避免使用此包，转而选择其他活跃维护的替代品。

接下来，我们聚焦于四个仍在积极维护的库：@zxing/library、html5-qrcode、jsqr 和 qr-scanner。

🔍 核心定位：你是要“引擎”还是要“整车”？

理解这些库的本质差异，关键在于区分 底层解码引擎 和 完整扫码组件。

• jsqr 是纯粹的 解码引擎：它只做一件事 —— 接收 RGBA 像素数组，返回解码结果。不处理摄像头、不渲染视频、不管理权限。
• @zxing/library 是 多功能解码引擎：支持 QR Code、EAN、UPC 等多种条码格式，提供解码器对象，但仍需你自行搭建视频流管道。
• html5-qrcode 和 qr-scanner 是 完整扫码组件：它们封装了从请求摄像头权限、渲染视频预览到连续扫描的全过程，提供简单 API 即可启动扫码。

示例：从零开始扫码需要多少代码？

jsqr（仅解码）

// 你需要自己获取图像数据（例如从 canvas）
const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);

// 调用 jsqr 解码
const code = jsQR(imageData.data, imageData.width, imageData.height);
if (code) {
  console.log('Found QR code:', code.data);
}

@zxing/library（需手动管理视频流）

import { BrowserMultiFormatReader } from '@zxing/library';

const codeReader = new BrowserMultiFormatReader();
const videoInputDevices = await codeReader.listVideoInputDevices();
const deviceId = videoInputDevices[0].deviceId;

// 手动将视频元素传入，并处理结果回调
codeReader.decodeFromVideoDevice(deviceId, 'videoElementId', (result, err) => {
  if (result) {
    console.log('Decoded:', result.getText());
  }
});

html5-qrcode（开箱即用）

import { Html5Qrcode } from 'html5-qrcode';

const html5QrCode = new Html5Qrcode('reader-container');

html5QrCode.start(
  { facingMode: 'environment' }, // 移动端后置摄像头
  { fps: 10, qrbox: { width: 250, height: 250 } },
  (decodedText) => {
    console.log('Scanned:', decodedText);
  }
);

qr-scanner（简洁 API）

import QrScanner from 'qr-scanner';

const video = document.createElement('video');
const qrScanner = new QrScanner(video, result => {
  console.log('Scanned:', result);
});

qrScanner.start(); // 自动请求权限并开始扫描

💡 关键区别：jsqr 和 @zxing/library 要求你构建整个扫码流程；html5-qrcode 和 qr-scanner 则为你打包好了这一切。

📱 移动端体验：谁更懂手机？

在移动端，扫码体验受摄像头切换、对焦、性能影响极大。

• html5-qrcode 显式支持 { facingMode: 'environment' }，可直接调用后置摄像头，并允许通过 qrbox 限制扫描区域，减少误扫。它还处理了 iOS Safari 的一些兼容性问题。
• qr-scanner 内置了针对移动设备的优化，包括自动请求高分辨率视频流，并利用 Web Worker 在后台解码，避免卡顿。其文档特别强调了移动端测试。
• @zxing/library 虽然能工作，但你需要自己处理 facingMode 和分辨率设置，否则默认可能打开前置摄像头。
• jsqr 完全不涉及设备层，移动端体验取决于你如何获取图像帧。

移动端最佳实践示例

html5-qrcode 正确配置后置摄像头

html5QrCode.start(
  { facingMode: 'environment' }, // 关键：指定后置
  { fps: 12, qrbox: 250 },
  onScanSuccess
);

qr-scanner 自动优化

// 默认尝试使用后置摄像头，并启用 worker
const qrScanner = new QrScanner(video, onScan, {
  highlightScanRegion: true,
  highlightCodeOutline: true
});

相比之下，使用 @zxing/library 时，你必须手动构造设备约束：

const constraints = { video: { facingMode: 'environment' } };
const devices = await navigator.mediaDevices.enumerateDevices();
// 还需筛选出 rear camera 的 deviceId...

⚙️ 控制粒度：你需要多细的掌控？

如果你的应用需要精细控制扫描行为（例如暂停/恢复、动态切换分辨率、自定义扫描区域），不同库的能力差异明显。

• @zxing/library 提供最细粒度的控制：你可以随时停止解码器、更换视频源、调整解码提示（hints），甚至同时运行多个解码器。
• html5-qrcode 提供 pause() / resume() 方法，并允许在启动后动态修改部分配置（如 fps），但无法在运行时更改扫描区域大小。
• qr-scanner 支持 stop() / start()，并可通过 setCamera() 切换摄像头，但缺乏对解码参数的直接暴露。
• jsqr 的控制完全由你掌握，因为你负责每一帧的输入。

动态暂停/恢复扫描示例

html5-qrcode

// 启动后
await html5QrCode.start(...);

// 暂停
await html5QrCode.pause();

// 恢复
await html5QrCode.resume();

qr-scanner

qrScanner.start(); // 开始
qrScanner.stop();  // 停止（不会释放摄像头）
qrScanner.destroy(); // 彻底清理

@zxing/library

let decoding = true;

codeReader.decodeFromVideoDevice(deviceId, 'video', (result, err) => {
  if (result && decoding) {
    console.log(result.getText());
    decoding = false; // 手动停止后续回调
    codeReader.reset(); // 清理解码器
  }
});

// 恢复需重新调用 decodeFromVideoDevice

🧪 性能与准确性：谁更快更准？

所有库底层都基于类似算法（如 ZXing 或 jsQR），但实现细节影响实际表现。

• qr-scanner 因使用 Web Worker，主线程不会被阻塞，在低端设备上更流畅。
• html5-qrcode 允许你通过 fps 限制帧率，平衡性能与电量消耗。
• @zxing/library 性能取决于你如何控制解码频率（例如是否每帧都解码）。
• jsqr 本身很快，但如果你在主线程高频调用，仍可能导致卡顿。

📌 实测建议：在目标设备上用真实二维码测试。某些库对模糊、倾斜或低光照下的二维码识别率更高，这往往取决于预处理逻辑（如二值化、滤波），而不仅是解码算法。

🛠️ 错误处理与调试

健壮的扫码功能必须妥善处理权限拒绝、设备无摄像头、解码失败等情况。

html5-qrcode 提供详细的错误回调：

html5QrCode.start(
  constraints,
  config,
  onSuccess,
  (errorMessage, error) => {
    if (error.name === 'NotAllowedError') {
      alert('请允许摄像头权限');
    }
  }
);

qr-scanner 抛出异常，需 try/catch：

try {
  await qrScanner.start();
} catch (e) {
  if (e.message?.includes('No suitable camera')) {
    alert('未找到摄像头');
  }
}

@zxing/library 在回调中传递 error 对象：

codeReader.decodeFromVideoDevice(deviceId, 'video', (result, err) => {
  if (err && !(err instanceof NotFoundException)) {
    console.error('Scan error:', err);
  }
});

jsqr 无错误概念 —— 如果无法解码，直接返回 null。

✅ 总结：如何选择？

💡 最终建议

• 多数项目：从 html5-qrcode 开始。它平衡了易用性、功能和兼容性，能满足 90% 的需求。
• 高性能优先：若目标用户主要在现代移动设备上使用，且扫码是核心功能，尝试 qr-scanner。
• 特殊需求：如需扫描商品条形码，或深度集成到复杂 UI 中，则投入时间学习 @zxing/library。
• 极简场景：如果只是偶尔解析一张上传的图片，jsqr 是最轻量的选择。

记住：没有“最好”的库，只有“最合适”你当前项目的工具。先明确需求，再动手编码。