在Node.js服务端开发中，二维码生成是一项常见需求，无论是用于支付跳转、设备绑定还是电子票务，都需要稳定且可控的输出方案。qrcode是一个成熟的第三方模块，它封装了二维码的编码算法，并提供了多种输出格式的支持，其中SVG和PNG是最常被使用的两种。理解它们之间的差异以及正确的调用方式，能够避免很多线上渲染异常。
qrcode模块的基础安装与API结构
要在项目中使用qrcode模块，首先需要通过npm进行安装。该模块同时支持Promise风格与回调风格的函数，常用的方法包括toString、toDataURL和toFile。其中toString可以指定类型为svg从而直接拿到矢量文本，而toBuffer或toFile在指定类型为png时能够生成二进制图像。这种统一的入口设计让开发者无需引入多个库即可完成多格式输出。
在引入模块时，通常使用require('qrcode')或ESM的import QRCode from 'qrcode'。模块内部依赖了对 Reed-Solomon 纠错算法的实现，因此在生成时可以传入errorCorrectionLevel参数，可选值有L、M、Q、H，等级越高抗遮挡能力越强，但点阵越密、尺寸越大。合理利用该参数可以在印刷清晰度和信息容量之间取得平衡。
下面是一个最基础的安装与简单调用示例，展示如何异步生成一段文本对应的二维码SVG字符串：
const QRCode = require('qrcode');
async function generateSVG() {
try {
const svgString = await QRCode.toString('https://ipipp.com', {
type: 'svg',
errorCorrectionLevel: 'M'
});
console.log(svgString.slice(0, 120));
} catch (err) {
console.error('生成失败', err);
}
}
generateSVG();
SVG输出的原理与适用场景
SVG全称是可缩放矢量图形，qrcode模块在输出SVG时，会将每一个黑色模块转换为<rect>或者<path>元素进行描述。因为是基于坐标和尺寸的数学描述，所以在任意倍率放大下都不会出现锯齿或模糊。这对于需要将二维码印刷在大幅海报、包装盒上的业务非常关键，同时也方便前端通过CSS改变其填充颜色而不必重新生成。
除了清晰度优势，SVG文本本身可以被Gzip压缩到很小，当接口直接返回SVG字符串时，网络传输成本低于PNG。不过SVG的解析需要浏览器或客户端支持矢量渲染，在极少数老旧扫码App的内置浏览器中可能存在兼容风险。此外如果二维码内容很长且纠错级别高，SVG的节点数量会明显增多，导致DOM解析变慢，此时应评估是否改为PNG。
以下示例演示如何将SVG写入文件，并附带了简单的尺寸与边距控制：
const fs = require('fs');
const QRCode = require('qrcode');
async function writeSVGFile() {
const svg = await QRCode.toString('order-20240512-001', {
type: 'svg',
margin: 2,
width: 300,
errorCorrectionLevel: 'Q'
});
fs.writeFileSync('order.svg', svg);
console.log('SVG文件已写出');
}
writeSVGFile();
PNG输出的原理与性能对比
与SVG不同，PNG是位图格式，qrcode模块在生成PNG时会先在内存中构建像素矩阵，再根据指定的width和scale参数进行栅格化，最终编码为PNG二进制流。每一个二维码模块对应若干个像素块，因此放大后会出现明显马赛克。但它的优势在于几乎所有图像解码器、扫码摄像头固件都能正确识别，稳定性极高。
在Node.js中，使用toBuffer拿到PNG的Buffer后，可以直接通过HTTP响应返回，也可存储到对象存储中。PNG生成会消耗一定的CPU进行压缩，如果接口瞬时并发高，建议增加缓存层或使用worker_threads隔离计算。对比SVG，PNG在内容较短时体积可能更小，但内容越长越不如SVG紧凑。
下面的代码展示了如何生成PNG Buffer并模拟写入文件，同时设置了较高的像素密度以适应高清屏：
const fs = require('fs');
const QRCode = require('qrcode');
async function writePNGBuffer() {
const pngBuffer = await QRCode.toBuffer('https://ipipp.com/login?t=123', {
type: 'png',
width: 512,
margin: 1,
errorCorrectionLevel: 'H'
});
fs.writeFileSync('login.png', pngBuffer);
console.log('PNG Buffer长度:', pngBuffer.length);
}
writePNGBuffer();
格式选型与错误处理建议
实际项目中应当结合展示终端来做选型。如果二维码主要出现在App原生页面或经过转码打印的纸质单据，PNG是稳妥选择；如果是官网下载的电子发票、可缩放的Web页面，SVG能提供更优质的体验。也可以在同一接口中根据请求头字段返回不同格式，提升灵活性。
使用qrcode模块时，常见的错误是传入了非法内容导致抛出异常，或者纠错级别设置过高使得小尺寸下无法扫码。建议在服务启动阶段用真实业务数据做一次扫码测试，并记录生成耗时。对于批量任务，可以复用模块实例并利用Promise.all控制并发，避免事件循环阻塞。
最后给出一个简单的格式路由示例，根据参数决定输出类别：
const QRCode = require('qrcode');
async function outputByFormat(format, text) {
if (format === 'svg') {
return await QRCode.toString(text, { type: 'svg' });
}
return await QRCode.toBuffer(text, { type: 'png', width: 400 });
}
outputByFormat('png', 'test-route').then(buf => {
console.log('拿到PNG Buffer:', Buffer.isBuffer(buf));
});