JavaScript 二维码生成库深度对比：qrcode vs qr-image vs qr.js

在 Web 开发中，生成二维码是一个常见需求，无论是用于分享链接、支付接口还是身份验证。qrcode、qr-image 和 qr.js 是 npm 上最常被提及的三个包，但它们的内部实现、API 设计和维护状态差异巨大。本文将从架构师视角，深入分析它们的技术细节，帮助你在项目中做出正确选择。

🛠️ API 设计风格：异步 Promise 与同步阻塞

现代 JavaScript 开发高度依赖异步操作，尤其是涉及图像处理或 I/O 时。这三个库在处理方式上有明显区别。

qrcode 采用基于 Promise 的异步 API。

• 适合非阻塞操作，避免阻塞事件循环。
• 支持 async/await 语法，代码更清晰。

// qrcode: 异步 Promise API
const QRCode = require('qrcode');

async function generate() {
  // 返回 Data URL 字符串
  const dataUrl = await QRCode.toDataURL('https://example.com');
  console.log(dataUrl);
}

qr-image 提供同步和流式 API。

• 同步方法会阻塞线程，适合简单脚本。
• 流式方法适合大文件或管道处理。

// qr-image: 同步与流式 API
const qr = require('qr-image');

// 同步生成缓冲区（阻塞）
const pngBuffer = qr.imageSync('https://example.com', { type: 'png' });

// 流式生成（非阻塞）
const stream = qr.image('https://example.com', { type: 'png' });
stream.pipe(require('fs').createWriteStream('qrcode.png'));

qr.js 主要是同步操作，依赖 DOM。

• 直接在浏览器中操作 DOM 元素。
• 没有原生 Promise 支持，需要手动封装。

// qr.js: 同步 DOM 操作
const QRCode = require('qr.js');

// 必须传入一个 DOM 元素
const element = document.getElementById('qrcode');
const qr = new QRCode(element, {
  text: 'https://example.com',
  width: 128,
  height: 128
});

🖼️ 输出格式与环境支持

输出格式决定了你能在哪里使用生成的二维码，以及如何处理它。

qrcode 支持最广泛的格式。

• 浏览器：Canvas、SVG、Data URL。
• Node.js：PNG 缓冲、UTF8 终端字符。
• 跨平台一致性最好。

// qrcode: 多种输出格式
// 生成 SVG 字符串
const svg = await QRCode.toString('https://example.com', { type: 'svg' });

// 生成 Node.js Buffer
const buffer = await QRCode.toBuffer('https://example.com', { type: 'png' });

qr-image 专注于二进制图片。

• 主要输出 PNG、SVG、EPS 的缓冲或流。
• 不适合直接在浏览器 Canvas 上绘制，更适合服务端保存文件。

// qr-image: 二进制输出
// 生成 SVG 字符串
const svgStream = qr.image('https://example.com', { type: 'svg' });

// 生成 PNG 缓冲区
const pngBuffer = qr.imageSync('https://example.com', { type: 'png' });

qr.js 仅限于浏览器 Canvas 或 Data URL。

• 依赖浏览器环境，无法在纯 Node.js 服务端运行（除非模拟 DOM）。
• 功能单一，难以自定义样式。

// qr.js: 仅支持浏览器环境
// 库本身直接渲染到传入的 DOM 节点
// 无法直接获取 Buffer 或 SVG 字符串，除非额外处理 Canvas
const canvas = document.createElement('canvas');
const qr = new QRCode(canvas, { text: 'https://example.com' });

📦 依赖与体积考量

虽然我们不讨论具体数字，但依赖关系直接影响项目的构建复杂度和安全性。

qrcode 依赖较少且模块化。

• 核心逻辑与渲染层分离。
• 可以按需引入特定渲染器（如只引入 SVG 渲染器）。

// qrcode: 按需引入
// 仅引入 SVG 渲染功能，减小打包体积
const QRCode = require('qrcode/lib/renderer/svg');

qr-image 依赖图像处理库。

• 内部依赖 pngjs 等库处理二进制。
• 在浏览器端使用需要打包这些二进制处理库，体积较大。

// qr-image: 内部依赖较重
// 通常只在 Node.js 使用，避免打包进前端代码
const qr = require('qr-image');

qr.js 无外部依赖但代码老旧。

• 单文件实现，看似轻量。
• 但代码风格过时，缺乏现代优化。

// qr.js: 无依赖但过时
// 直接引入即可，但缺乏模块化支持
const QRCode = require('qr.js');

⚠️ 维护状态与安全性

这是架构决策中最关键的一环。使用不再维护的库会带来安全风险和兼容性问题。

qrcode 处于活跃维护状态。

• 定期修复漏洞，支持新版本的 Node.js。
• 社区贡献活跃，文档完善。
• 推荐用于所有新项目。

qr-image 维护频率较低。

• 功能稳定，但新特性添加缓慢。
• 适合稳定的服务端工具脚本，不适合核心业务逻辑。

qr.js 已停止维护。

• 最后更新距今已久，存在已知问题未修复。
• 不支持 UTF-8 字符集（如中文）的情况较多，容易乱码。
• 强烈建议避免使用。

// qr.js: 中文支持问题示例
// 在旧版本中，包含中文的文本可能导致生成失败或乱码
const qr = new QRCode(element, { text: '你好世界' }); // 可能出错

📊 总结对比表

💡 最终建议

qrcode 是当今的标准选择 🏆。它平衡了功能、性能和易用性，无论是前端展示还是后端生成都能胜任。如果你的项目需要生成二维码，请直接使用它。

qr-image 适合特定场景 🔧。如果你已经在 Node.js 服务端处理图片流，并且不需要 Canvas 操作，它可以作为轻量级替代方案。

qr.js 应被淘汰 🗑️。除非你正在维护一个五年前的老项目且无法重构，否则不要在任何新代码中引入它。它的局限性（尤其是字符编码问题）会给用户带来糟糕的体验。

核心原则：选择库时，不仅要看它能做什么，还要看它未来能否持续支持你的项目。qrcode 的活跃维护意味着当 Node.js 或浏览器更新时，它会更快地适配，减少你的技术债务。