简介jsQR是一个零依赖、纯JavaScript实现的二维码识别库可在浏览器端离线解析非常适合Web前端新手快速入手。资源包内含一个完整可运行的识别示例共5个文件、仅79KB包括两个JS脚本jsQR核心解码库和jQuery辅助库、一个HTML演示页面以及两张二维码测试图。页面已封装好从用户选择本地图片、利用Canvas提取像素数据、调用jsQR识别并输出结果的完整链路解压后打开HTML即可直接验证效果。目前已有1821人学习该资源。这份示例还展示了FileReader读取文件、Image对象绘制到Canvas等前端必备技巧并讨论了图像清晰度对识别成功率的影响及常见错误处理与性能优化思路帮助初学者理解原理并快速迁移到摄像头实时识别或批量处理场景。压缩包体积小巧非常适合作为项目起步模板或教学演示。1. jsQR 识别二维码一个纯前端例子能解决什么jsQR 识别二维码这件事很多前端同事的第一反应是找后端接口或者接第三方 SDK但实际上一个纯 JavaScript 实现的库就能在浏览器里完成解码。这个压缩包里带的 jsQRTest 目录就是一套可以直接跑通的完整例子一个 HTML 文件、一个 jsQR.js、两张测试二维码图片外加一个 jQuery 3.4.1。它解决的场景很具体——H5 页面里识别二维码、微信里长按图片识别、或者摄像头扫码都可以在前端独立完成不需要后端参与。适合刚接触二维码识别的 Web 开发者也适合想在现有项目里快速集成扫码功能又不想引重型框架的人。接下来我会把这个包拆开从原理讲到踩坑。2. 原理与资源包拆解jsQR 如何从像素变成结果2.1 为什么选 jsQR纯前端、零依赖、离线可用jsQR 的核心价值在于它把二维码解码整个塞进了浏览器。主流的识别方案无非三种后端调 ZXing、原生 App 里用 Camera 扫、或者前端纯 JS 解码。前两者都要维护服务端或原生代码而 jsQR 只需要一份 JS 文件逻辑全部跑在浏览器里。前端拿到的图片视频帧根本不需要上传这对隐私敏感的业务场景特别友好。它的工作原理大致是把图像转换成灰度矩阵然后通过扫描定位三个角上的回字型定位图案position detection pattern确定二维码的方向和版本再按版本对应的矩阵尺寸采样模块最后执行纠错和译码。所以它接收的不是 DOM 元素也不是图片路径而是像素数据。这也是很多新手第一次用的时候卡住的地方——必须先把图片画到 canvas 上再把 canvas 的 ImageData 取出来交给 jsQR。选型时我一般会在 jsQR、Quagga2、ZXing 的 JS 移植版之间权衡。对比下来大致是这样方案依赖识别能力适用场景jsQR无外部依赖二维码为主静态图片、摄像头扫码Quagga2无外部依赖条形码为主二维码弱物流条码、一维码ZXing JS 移植需要适配层二维码条码都行想要 ZXing 生态的老项目如果目标明确是识别二维码jsQR 是最轻的一条路。资源包里那份 jsQR.js 是压缩过的完整库不需要额外装 npm 包。2.2 资源包文件逐一拆解解压后目录结构大概是这样的文件作用1.html示例页面包含图片上传和识别逻辑jsQR.jsjsQR 核心库压缩版本jquery-3.4.1.min.jsjQuery 3.4.1页面里辅助操作 DOMQR.jpg测试二维码图片 1QR1.jpg测试二维码图片 2用 jQuery 只是示例代码里的 DOM 操作方便jsQR 本身完全不需要 jQuery。所以你后续集成到自己的项目里完全可以把 jQuery 扔掉只用原生 JS 配合 jsQR.js。目录里的两张测试图是拿来验证识别流程用的先跑通它们再换成自己的图片排错会容易很多。2.3 核心调用链canvas 取像素 → jsQR 解码jsQR 的调用入口就一个函数jsQR(data, width, height)。data是包含 RGBA 颜色值的 Uint8ClampedArraywidth和height是图像的宽高。常见做法是从 canvas 的getImageData()里拿这份数据。// 1.html 里的核心三行 const ctx canvas.getContext(2d); ctx.drawImage(img, 0, 0); // 把图片画到画布上 const imageData ctx.getImageData(0, 0, canvas.width, canvas.height); const code jsQR(imageData.data, imageData.width, imageData.height);getImageData()返回的imageData.data就是像素数组每四个字节表示一个像素的 R、G、B、A 值。jsQR 会把 RGBA 转成灰度再去做二值化定位。这里有个容易被忽略的点drawImage之前必须确保canvas.width和canvas.height已经设置成图片的实际尺寸否则画布默认是 300×150图片会被裁剪或缩放二维码自然识别不出来。如果code为null说明图像里没找到可解码的二维码如果非null它的data字段就是二维码里存的内容。这个返回对象的完整结构包括data内容、location二维码在图像中的位置和角点坐标、以及version和bytes等底层信息。日常业务里 90% 的时间只需要code.data但location在做扫码框或 AR 特效时会用到。3. 跑通 1.html上传图片、读取像素与输出二维码内容3.1 页面骨架input 选文件与结果挂载资源包里的 1.html 走的是文件上传路线页面先放一个input[typefile]再放一个结果显示区。用户在微信里打开 H5 页或者直接电脑浏览器选本地图片就能完成识别。这种方式实现成本最低适合先验证整条链路。input typefile idupload acceptimage/* / pre idresult等待选择图片.../preacceptimage/*会过滤掉非图片文件。用pre显示结果是因为二维码内容可能带换行pre能保留格式比div直观。3.2 FileReader 读取图片的三段式流程从用户选文件到拿到可以识别的像素中间要经历 file - dataURL - Image - canvas 的转换。这段逻辑是整套识别的核心我把它完整拆开讲。const input document.getElementById(upload); input.addEventListener(change, function (event) { const file event.target.files[0]; if (!file) return; // 第一步用 FileReader 把文件读成 dataURL const reader new FileReader(); reader.onload function (e) { const dataURL e.target.result; const img new Image(); // 第二步dataURL 赋值给 Image等图片加载完 img.onload function () { const canvas document.createElement(canvas); canvas.width img.width; canvas.height img.height; const ctx canvas.getContext(2d); ctx.drawImage(img, 0, 0); // 第三步取像素数据交给 jsQR const imageData ctx.getImageData(0, 0, canvas.width, canvas.height); const code jsQR(imageData.data, imageData.width, imageData.height); document.getElementById(result).textContent code ? 识别结果 code.data : 未找到二维码; }; img.src dataURL; }; reader.readAsDataURL(file); });这段代码每一步都有讲究。readAsDataURL会把文件读成 base64 格式img.src dataURL之后浏览器异步加载这张图片。onload回调里必须重新createElement(canvas)而不是复用display:none的隐藏 canvas原因是我在下一章提到的 canvas 污染问题。3.3 canvas 绘制与像素提取的参数细节drawImage有多个重载示例里用的是最简形式drawImage(img, 0, 0)意思是从图片左上角开始完整绘制。如果图片有 EXIF 旋转信息手机拍的照片常见img.width和img.height是解码后的实际尺寸canvas 按这个尺寸创建即可不会因为旋转信息产生偏移。getImageData(0, 0, canvas.width, canvas.height)四个参数分别是取像素的起始 x、起始 y、取多宽、取多高。取整张图的像素传给 jsQR是最稳的做法。有些同学想优化性能只取二维码中心的区域但这样一旦二维码不在中心就识别失败了没有特殊需求建议整张图输入。getImageData返回的imageData.data是Uint8ClampedArray直接作为jsQR()的第一个参数即可不需要做任何类型转换。imageData.width和imageData.height就是刚才 canvas 的宽高保持一致是解码正确的前提。3.4 识别结果的三个维度内容、位置与可靠性成功的返回对象code包含这几个关键字段字段类型含义datastring二维码存储的内容可能是文本、URL 或 JSONlocationobject二维码三个定位角点和中心点坐标bytesUint8ClampedArray原始解码字节versionnumber二维码版本号1 到 40code.location里有topLeftCorner、topRightCorner、bottomLeftCorner和bottomRightCorner每个角点有x、y、estimatedModuleSize三个属性。如果你想在图片上画框标出二维码位置用location的画一个四边形即可。version这个字段一般用不上但在调试某些畸形二维码时它能帮你判断是不是版本矩阵采样出了问题。3.5 在 1.html 里跑起来的最小改动资源包里的 1.html 已经是完整可运行的双击打开就能用。但要注意直接用file://协议打开时有些浏览器策略会限制 file 输入框读取文件的方式如果发现点击没反应换 Chrome 或者用本地服务器方式启动。# 在 jsQRTest 目录下执行 python -m http.server 8080然后浏览器访问http://localhost:8080/1.html。这一步能规避掉大多数因为本地文件权限导致的怪问题。跑通之后把 QR.jpg 和 QR1.jpg 分别上传应该都能正确识别出内容。如果有一个失败大概率是测试图本身故意做了某种干扰比如反色具体排查见下一章。4. 避坑指南jsQR 识别失败的五个常见问题4.1 最常见的五个坑与排查顺序jsQR 本身很稳定但接入的时候翻车点多在外围的数据流。我自己在这套例子上至少栽过五个跟头每个都是典型的现象好观察、原因不好找。坑一canvas 被污染getImageData 直接抛 SecurityError现象图片明明加载出来了执行ctx.getImageData()时控制台报错SecurityError: The operation is insecure二维码识别结果永远是 null。原因浏览器安全策略规定canvas 里画了跨域图片比如从 CDN 加载的图片之后canvas 就被污染了不再允许读取像素数据。双击本地file://打开的 HTML 里把磁盘上的图片画进 canvas 再读像素同样会被某些浏览器视为不安全操作。解决思路是先把图片转成 dataURL 再画。上面第 3 章的例子用FileReader.readAsDataURL读文件天然规避了这个问题。如果图片本来就有 URL 来源可以先fetch它再转成 blob 和 dataURL而不是直接给img.src赋远程地址。最简单粗暴的做法就是本地起一个静态服务器通过http://localhost访问页面所有同源问题直接消失。坑二图片模糊或二维码占比太小识别率直线下降现象二维码只有整张图片的几十分之一超过 5 厘米距离拍的照片上传后jsQR 返回 null稍微清楚点的识别结果时好时坏。原因jsQR 的定位算法依赖对模块黑白色块边缘的检测。二维码在图像里占比太小每个模块可能只占几个像素二值化时一个噪点就可能导致整个定位图案匹配失败。解决在交给 jsQR 之前先把 canvas 放大让二维码在画布里至少占 200×200 像素以上。常见做法是把短边放大到 640并保持宽高比。// 识别前对 canvas 做缩放增强 const maxSide 640; let drawW img.width; let drawH img.height; if (Math.max(drawW, drawH) maxSide) { const scale maxSide / Math.max(drawW, drawH); drawW Math.round(drawW * scale); drawH Math.round(drawH * scale); } canvas.width drawW; canvas.height drawH; ctx.drawImage(img, 0, 0, drawW, drawH);注意canvas.width 赋值本身就是清空画布的操作所以必须放在drawImage之前。放大之后如果还是失败可以再叠加一个灰度对比度增强用ctx.filter contrast(1.2)不过这个属性在 Safari 里支持度一般线下测试优先 Chrome。坑三反色二维码黑底白码识别不出来现象普通白底黑码都能识别但遇到黑底白码的二维码jsQR 稳定返回 null。这在支付宝和微信的一些营销码里很常见。原因jsQR 内部的二值化逻辑默认深色模块在前景、浅色在后景。反色二维码整体像素极性反转定位图案的扫描线匹配不上。解决识别前把像素数据做一次颜色反转把 RGBA 里的 RGB 都取反Alpha 不变。const data imageData.data; for (let i 0; i data.length; i 4) { data[i] 255 - data[i]; // R data[i 1] 255 - data[i 1]; // G data[i 2] 255 - data[i 2]; // B // data[i 3] 是 alpha不反转 } const code jsQR(data, imageData.width, imageData.height); if (!code) { // 如果不放心可以再对原图识别一次做双保险 const code2 jsQR(imageData.data, imageData.width, imageData.height); }实际操作里我倾向于正反两遍都识别先原图失败再反转。这样普通二维码不经过反转流程不损失识别率反色码也能兜住。坑四script 引入 jsQR 后在模块化代码里调用报 undefined现象页面里写了script srcjsQR.js/script但在另一个模块文件里写jsQR(...)控制台报jsQR is not defined。原因压缩版 jsQR.js 会把 API 挂到window上还是导出到 CommonJS取决于构建配置。script标签引入后通常可以在全局访问但如果你的项目开启了 ES Module 严格模式或者typemodule全局变量不一定暴露。解决统一入口。资源包里既然是 script 标签方式就保持全部用 script。如果二开项目里是 Webpack/Vite 环境就直接npm install jsqr然后import { jsQR } from jsqr不要再混用全局版本。我踩过的坑就是在 Vite 项目里既装了 npm 包又手动引了旧版 jsQR.js结果两个实例冲突识别率反而下降。坑五图片带白边或二维码嵌在复杂背景里定位角点被淹没现象二维码是印在纸箱、宣传海报上的背景有纹理或文字。上传后 jsQR 返回 null或者识别出错误的内容。原因jsQR 的定位图案要求周围有足够大的空白区域俗称 quiet zone标准要求至少 4 个模块宽度。复杂背景的纹理和文字会产生伪边缘导致扫描匹配错乱。解决先用 canvas 对二维码区域做裁剪手动把四周扩一圈白边后再传给 jsQR。如果不知道二维码在哪可以先把整个图像做一次高斯模糊再识别但实战更常用的是让用户把二维码尽量对准画面中心做一个人工扫码框。这类问题在摄像头实时扫描时更明显第五章的抽帧策略里我会说一个折中的处理。4.2 调试辅助把灰度图和定位结果可视化遇到识别失败最怕的就是黑匣子式排查。我一般会在页面上临时加一个调试面板把传给 jsQR 之前的 canvas 显示出来人眼能看到的明显问题比如画布空白、图片被裁剪、颜色被反转就都不用来回猜。// 调试把处理后的 canvas 挂到页面上 const debugCanvas document.getElementById(debugCanvas); const debugCtx debugCanvas.getContext(2d); debugCanvas.width imageData.width; debugCanvas.height imageData.height; debugCtx.putImageData(imageData, 0, 0);putImageData和getImageData是互逆操作把 ImageData 原样画到另一个 canvas 上。这一步不经过drawImage所以不会触发 canvas 污染限制。看到画布内容之后再想想是模糊了是反色了还是背景干扰太强比盲试参数高效太多。5. 从静态图片到摄像头getUserMedia 实时扫码与性能调优5.1 摄像头接入getUserMedia 与 video 标签很多实际业务里用户不可能先去拍照再上传要的是打开页面直接扫码。这套例子的思路同样适用只要把图片来源从用户选择文件换成摄像头画面即可。const video document.getElementById(video); async function startCamera() { const stream await navigator.mediaDevices.getUserMedia({ video: { facingMode: environment, width: 1280, height: 720 } }); video.srcObject stream; await video.play(); }facingMode: environment是后置摄像头手机扫码必须用这个否则默认前置摄像头对着用户的脸。width和height决定视频流的分辨率不是越高越好我在 5.3 节单独说。5.2 抽帧循环requestAnimationFrame 里的识别节奏摄像头是连续的视频流但 jsQR 识别一次需要几毫秒到几十毫秒不可能每一帧都识别。常见做法是用requestAnimationFrame循环里加一个节流阀每 N 帧识别一次。let frameCount 0; const FRAME_INTERVAL 5; // 每 5 帧识别一次约 100ms 一次 function scanLoop() { frameCount; if (frameCount % FRAME_INTERVAL 0) { scanFrame(); } requestAnimationFrame(scanLoop); } function scanFrame() { const canvas document.createElement(canvas); canvas.width video.videoWidth; canvas.height video.videoHeight; const ctx canvas.getContext(2d); ctx.drawImage(video, 0, 0); const imageData ctx.getImageData(0, 0, canvas.width, canvas.height); const code jsQR(imageData.data, imageData.width, imageData.height); if (code) { // 识别到就停或者震动提示 navigator.vibrate navigator.vibrate(100); handleResult(code.data); } }FRAME_INTERVAL是节流参数5 帧一次在 30fps 的视频流里就是每 166ms 识别一次。如果识别太频繁CPU 占用高手机会发热太久则二维码从画面中扫过容易漏掉。我一般从 5 起步识别率不够再降到 3发热严重再升到 8。5.3 性能参数分辨率、抽帧频率与识别率的平衡摄像头扫码的性能调优本质是在三项之间找平衡视频分辨率单帧处理耗时识别率设备负载640×480快约 8ms中等近距离码可识别低1280×720中约 15ms高远距离和小时可识别中1920×1080慢约 30ms最高但容易掉帧高经验值是 720p 加 5 帧抽一。1080p 在低端安卓机上单帧处理时间可能超过帧间隔导致requestAnimationFrame堆积画面卡顿。另外可以做一个降级第一次识别失败时把 canvas 区域缩放到原图一半再做一次识别。因为二维码被缩小时相当于做了降采样模糊的影响会被抹平一些对轻微失焦的画面反而有效。// 降采样二次识别把 canvas 宽高各减半减少噪点干扰 const smallCanvas document.createElement(canvas); smallCanvas.width Math.floor(video.videoWidth / 2); smallCanvas.height Math.floor(video.videoHeight / 2); const sCtx smallCanvas.getContext(2d); sCtx.drawImage(video, 0, 0, smallCanvas.width, smallCanvas.height); const sData sCtx.getImageData(0, 0, smallCanvas.width, smallCanvas.height); const code2 jsQR(sData.data, sData.width, sData.height);这个办法在二维码过远、模块密集时效果显著。原理是降采样相当于做了平均滤波把高频噪点抹掉让定位图案的边缘更连续。5.4 扫到结果之后关闭视频流防止摄像头常亮这是新手最容易漏的环节。识别成功后如果直接跳转页面浏览器通常会自动释放摄像头但如果停留在当前页摄像头指示灯一直亮着用户会直接觉得隐私被侵犯。// 识别成功后关闭摄像头 function stopCamera() { if (video.srcObject) { const tracks video.srcObject.getTracks(); tracks.forEach(track track.stop()); video.srcObject null; } }track.stop()是真正关掉摄像头的唯一方法光把video标签隐藏或移除是没用的设备指示灯还亮着。我在做扫码登录页时就是漏了这一步被测试同事当成 bug 报了好几次。6. 封装成一个可复用模块初始化、回调与断流收尾摄像头扫码逻辑如果直接堆在页面里换一个项目就要重写一遍。我习惯把它封装成一个带回调的QrScanner类静态图片识别和摄像头识别共用一套核心。这里给出一个紧凑的封装版本class QrScanner { constructor(videoElement, onDetected) { this.video videoElement; this.onDetected onDetected; this.running false; this.stream null; this.canvas document.createElement(canvas); this.ctx this.canvas.getContext(2d); } start() { this.running true; navigator.mediaDevices.getUserMedia({ video: { facingMode: environment, width: 1280, height: 720 } }).then(stream { this.stream stream; this.video.srcObject stream; this.video.play(); this.loop(); }); } loop() { if (!this.running) return; if (this.video.readyState this.video.HAVE_ENOUGH_DATA) { this.canvas.width this.video.videoWidth; this.canvas.height this.video.videoHeight; this.ctx.drawImage(this.video, 0, 0); const imageData this.ctx.getImageData( 0, 0, this.canvas.width, this.canvas.height ); const code jsQR(imageData.data, imageData.width, imageData.height); if (code) { this.onDetected(code.data); this.stop(); // 扫到即停 return; } } requestAnimationFrame(() this.loop()); } stop() { this.running false; if (this.stream) { this.stream.getTracks().forEach(track track.stop()); this.stream null; this.video.srcObject null; } } } // 页面里使用 const scanner new QrScanner( document.getElementById(video), (result) { alert(扫码结果 result); } ); scanner.start();封装的关键是三个状态start、loop、stop形成一个闭环。loop里执行完一次识别后立即用requestAnimationFrame安排下一次扫到结果或手动stop都会让running变为 false循环自然终止。这样做的好处是调试时能随时从浏览器 console 里敲一句scanner.stop()救场。在真实项目里我会给这个封装再加两个功能一个是识别成功的防抖防止同一码连续触发多次事件另一个是空白帧跳过判断video.readyState和画布内容避免视频还没出画面就跑空循环消耗性能。资源包里的 1.html 和两张测试图本质上是把上面这套逻辑里最核心的静态图片识别那一环拿了出来。你先把 1.html 跑通摄像头扫码就是在它的基础上把图片来源换成视频流而已。从那以后我每次接扫码需求都会强制自己先走一遍这个流程本地文件识别 → 调试面板可视化 → 摄像头接入 → 封装模块四步做完基本不会翻车。希望帮到你。本文还有配套的精品资源点击获取
jsQR纯前端二维码识别：从图片像素到摄像头扫码的完整实践
简介jsQR是一个零依赖、纯JavaScript实现的二维码识别库可在浏览器端离线解析非常适合Web前端新手快速入手。资源包内含一个完整可运行的识别示例共5个文件、仅79KB包括两个JS脚本jsQR核心解码库和jQuery辅助库、一个HTML演示页面以及两张二维码测试图。页面已封装好从用户选择本地图片、利用Canvas提取像素数据、调用jsQR识别并输出结果的完整链路解压后打开HTML即可直接验证效果。目前已有1821人学习该资源。这份示例还展示了FileReader读取文件、Image对象绘制到Canvas等前端必备技巧并讨论了图像清晰度对识别成功率的影响及常见错误处理与性能优化思路帮助初学者理解原理并快速迁移到摄像头实时识别或批量处理场景。压缩包体积小巧非常适合作为项目起步模板或教学演示。1. jsQR 识别二维码一个纯前端例子能解决什么jsQR 识别二维码这件事很多前端同事的第一反应是找后端接口或者接第三方 SDK但实际上一个纯 JavaScript 实现的库就能在浏览器里完成解码。这个压缩包里带的 jsQRTest 目录就是一套可以直接跑通的完整例子一个 HTML 文件、一个 jsQR.js、两张测试二维码图片外加一个 jQuery 3.4.1。它解决的场景很具体——H5 页面里识别二维码、微信里长按图片识别、或者摄像头扫码都可以在前端独立完成不需要后端参与。适合刚接触二维码识别的 Web 开发者也适合想在现有项目里快速集成扫码功能又不想引重型框架的人。接下来我会把这个包拆开从原理讲到踩坑。2. 原理与资源包拆解jsQR 如何从像素变成结果2.1 为什么选 jsQR纯前端、零依赖、离线可用jsQR 的核心价值在于它把二维码解码整个塞进了浏览器。主流的识别方案无非三种后端调 ZXing、原生 App 里用 Camera 扫、或者前端纯 JS 解码。前两者都要维护服务端或原生代码而 jsQR 只需要一份 JS 文件逻辑全部跑在浏览器里。前端拿到的图片视频帧根本不需要上传这对隐私敏感的业务场景特别友好。它的工作原理大致是把图像转换成灰度矩阵然后通过扫描定位三个角上的回字型定位图案position detection pattern确定二维码的方向和版本再按版本对应的矩阵尺寸采样模块最后执行纠错和译码。所以它接收的不是 DOM 元素也不是图片路径而是像素数据。这也是很多新手第一次用的时候卡住的地方——必须先把图片画到 canvas 上再把 canvas 的 ImageData 取出来交给 jsQR。选型时我一般会在 jsQR、Quagga2、ZXing 的 JS 移植版之间权衡。对比下来大致是这样方案依赖识别能力适用场景jsQR无外部依赖二维码为主静态图片、摄像头扫码Quagga2无外部依赖条形码为主二维码弱物流条码、一维码ZXing JS 移植需要适配层二维码条码都行想要 ZXing 生态的老项目如果目标明确是识别二维码jsQR 是最轻的一条路。资源包里那份 jsQR.js 是压缩过的完整库不需要额外装 npm 包。2.2 资源包文件逐一拆解解压后目录结构大概是这样的文件作用1.html示例页面包含图片上传和识别逻辑jsQR.jsjsQR 核心库压缩版本jquery-3.4.1.min.jsjQuery 3.4.1页面里辅助操作 DOMQR.jpg测试二维码图片 1QR1.jpg测试二维码图片 2用 jQuery 只是示例代码里的 DOM 操作方便jsQR 本身完全不需要 jQuery。所以你后续集成到自己的项目里完全可以把 jQuery 扔掉只用原生 JS 配合 jsQR.js。目录里的两张测试图是拿来验证识别流程用的先跑通它们再换成自己的图片排错会容易很多。2.3 核心调用链canvas 取像素 → jsQR 解码jsQR 的调用入口就一个函数jsQR(data, width, height)。data是包含 RGBA 颜色值的 Uint8ClampedArraywidth和height是图像的宽高。常见做法是从 canvas 的getImageData()里拿这份数据。// 1.html 里的核心三行 const ctx canvas.getContext(2d); ctx.drawImage(img, 0, 0); // 把图片画到画布上 const imageData ctx.getImageData(0, 0, canvas.width, canvas.height); const code jsQR(imageData.data, imageData.width, imageData.height);getImageData()返回的imageData.data就是像素数组每四个字节表示一个像素的 R、G、B、A 值。jsQR 会把 RGBA 转成灰度再去做二值化定位。这里有个容易被忽略的点drawImage之前必须确保canvas.width和canvas.height已经设置成图片的实际尺寸否则画布默认是 300×150图片会被裁剪或缩放二维码自然识别不出来。如果code为null说明图像里没找到可解码的二维码如果非null它的data字段就是二维码里存的内容。这个返回对象的完整结构包括data内容、location二维码在图像中的位置和角点坐标、以及version和bytes等底层信息。日常业务里 90% 的时间只需要code.data但location在做扫码框或 AR 特效时会用到。3. 跑通 1.html上传图片、读取像素与输出二维码内容3.1 页面骨架input 选文件与结果挂载资源包里的 1.html 走的是文件上传路线页面先放一个input[typefile]再放一个结果显示区。用户在微信里打开 H5 页或者直接电脑浏览器选本地图片就能完成识别。这种方式实现成本最低适合先验证整条链路。input typefile idupload acceptimage/* / pre idresult等待选择图片.../preacceptimage/*会过滤掉非图片文件。用pre显示结果是因为二维码内容可能带换行pre能保留格式比div直观。3.2 FileReader 读取图片的三段式流程从用户选文件到拿到可以识别的像素中间要经历 file - dataURL - Image - canvas 的转换。这段逻辑是整套识别的核心我把它完整拆开讲。const input document.getElementById(upload); input.addEventListener(change, function (event) { const file event.target.files[0]; if (!file) return; // 第一步用 FileReader 把文件读成 dataURL const reader new FileReader(); reader.onload function (e) { const dataURL e.target.result; const img new Image(); // 第二步dataURL 赋值给 Image等图片加载完 img.onload function () { const canvas document.createElement(canvas); canvas.width img.width; canvas.height img.height; const ctx canvas.getContext(2d); ctx.drawImage(img, 0, 0); // 第三步取像素数据交给 jsQR const imageData ctx.getImageData(0, 0, canvas.width, canvas.height); const code jsQR(imageData.data, imageData.width, imageData.height); document.getElementById(result).textContent code ? 识别结果 code.data : 未找到二维码; }; img.src dataURL; }; reader.readAsDataURL(file); });这段代码每一步都有讲究。readAsDataURL会把文件读成 base64 格式img.src dataURL之后浏览器异步加载这张图片。onload回调里必须重新createElement(canvas)而不是复用display:none的隐藏 canvas原因是我在下一章提到的 canvas 污染问题。3.3 canvas 绘制与像素提取的参数细节drawImage有多个重载示例里用的是最简形式drawImage(img, 0, 0)意思是从图片左上角开始完整绘制。如果图片有 EXIF 旋转信息手机拍的照片常见img.width和img.height是解码后的实际尺寸canvas 按这个尺寸创建即可不会因为旋转信息产生偏移。getImageData(0, 0, canvas.width, canvas.height)四个参数分别是取像素的起始 x、起始 y、取多宽、取多高。取整张图的像素传给 jsQR是最稳的做法。有些同学想优化性能只取二维码中心的区域但这样一旦二维码不在中心就识别失败了没有特殊需求建议整张图输入。getImageData返回的imageData.data是Uint8ClampedArray直接作为jsQR()的第一个参数即可不需要做任何类型转换。imageData.width和imageData.height就是刚才 canvas 的宽高保持一致是解码正确的前提。3.4 识别结果的三个维度内容、位置与可靠性成功的返回对象code包含这几个关键字段字段类型含义datastring二维码存储的内容可能是文本、URL 或 JSONlocationobject二维码三个定位角点和中心点坐标bytesUint8ClampedArray原始解码字节versionnumber二维码版本号1 到 40code.location里有topLeftCorner、topRightCorner、bottomLeftCorner和bottomRightCorner每个角点有x、y、estimatedModuleSize三个属性。如果你想在图片上画框标出二维码位置用location的画一个四边形即可。version这个字段一般用不上但在调试某些畸形二维码时它能帮你判断是不是版本矩阵采样出了问题。3.5 在 1.html 里跑起来的最小改动资源包里的 1.html 已经是完整可运行的双击打开就能用。但要注意直接用file://协议打开时有些浏览器策略会限制 file 输入框读取文件的方式如果发现点击没反应换 Chrome 或者用本地服务器方式启动。# 在 jsQRTest 目录下执行 python -m http.server 8080然后浏览器访问http://localhost:8080/1.html。这一步能规避掉大多数因为本地文件权限导致的怪问题。跑通之后把 QR.jpg 和 QR1.jpg 分别上传应该都能正确识别出内容。如果有一个失败大概率是测试图本身故意做了某种干扰比如反色具体排查见下一章。4. 避坑指南jsQR 识别失败的五个常见问题4.1 最常见的五个坑与排查顺序jsQR 本身很稳定但接入的时候翻车点多在外围的数据流。我自己在这套例子上至少栽过五个跟头每个都是典型的现象好观察、原因不好找。坑一canvas 被污染getImageData 直接抛 SecurityError现象图片明明加载出来了执行ctx.getImageData()时控制台报错SecurityError: The operation is insecure二维码识别结果永远是 null。原因浏览器安全策略规定canvas 里画了跨域图片比如从 CDN 加载的图片之后canvas 就被污染了不再允许读取像素数据。双击本地file://打开的 HTML 里把磁盘上的图片画进 canvas 再读像素同样会被某些浏览器视为不安全操作。解决思路是先把图片转成 dataURL 再画。上面第 3 章的例子用FileReader.readAsDataURL读文件天然规避了这个问题。如果图片本来就有 URL 来源可以先fetch它再转成 blob 和 dataURL而不是直接给img.src赋远程地址。最简单粗暴的做法就是本地起一个静态服务器通过http://localhost访问页面所有同源问题直接消失。坑二图片模糊或二维码占比太小识别率直线下降现象二维码只有整张图片的几十分之一超过 5 厘米距离拍的照片上传后jsQR 返回 null稍微清楚点的识别结果时好时坏。原因jsQR 的定位算法依赖对模块黑白色块边缘的检测。二维码在图像里占比太小每个模块可能只占几个像素二值化时一个噪点就可能导致整个定位图案匹配失败。解决在交给 jsQR 之前先把 canvas 放大让二维码在画布里至少占 200×200 像素以上。常见做法是把短边放大到 640并保持宽高比。// 识别前对 canvas 做缩放增强 const maxSide 640; let drawW img.width; let drawH img.height; if (Math.max(drawW, drawH) maxSide) { const scale maxSide / Math.max(drawW, drawH); drawW Math.round(drawW * scale); drawH Math.round(drawH * scale); } canvas.width drawW; canvas.height drawH; ctx.drawImage(img, 0, 0, drawW, drawH);注意canvas.width 赋值本身就是清空画布的操作所以必须放在drawImage之前。放大之后如果还是失败可以再叠加一个灰度对比度增强用ctx.filter contrast(1.2)不过这个属性在 Safari 里支持度一般线下测试优先 Chrome。坑三反色二维码黑底白码识别不出来现象普通白底黑码都能识别但遇到黑底白码的二维码jsQR 稳定返回 null。这在支付宝和微信的一些营销码里很常见。原因jsQR 内部的二值化逻辑默认深色模块在前景、浅色在后景。反色二维码整体像素极性反转定位图案的扫描线匹配不上。解决识别前把像素数据做一次颜色反转把 RGBA 里的 RGB 都取反Alpha 不变。const data imageData.data; for (let i 0; i data.length; i 4) { data[i] 255 - data[i]; // R data[i 1] 255 - data[i 1]; // G data[i 2] 255 - data[i 2]; // B // data[i 3] 是 alpha不反转 } const code jsQR(data, imageData.width, imageData.height); if (!code) { // 如果不放心可以再对原图识别一次做双保险 const code2 jsQR(imageData.data, imageData.width, imageData.height); }实际操作里我倾向于正反两遍都识别先原图失败再反转。这样普通二维码不经过反转流程不损失识别率反色码也能兜住。坑四script 引入 jsQR 后在模块化代码里调用报 undefined现象页面里写了script srcjsQR.js/script但在另一个模块文件里写jsQR(...)控制台报jsQR is not defined。原因压缩版 jsQR.js 会把 API 挂到window上还是导出到 CommonJS取决于构建配置。script标签引入后通常可以在全局访问但如果你的项目开启了 ES Module 严格模式或者typemodule全局变量不一定暴露。解决统一入口。资源包里既然是 script 标签方式就保持全部用 script。如果二开项目里是 Webpack/Vite 环境就直接npm install jsqr然后import { jsQR } from jsqr不要再混用全局版本。我踩过的坑就是在 Vite 项目里既装了 npm 包又手动引了旧版 jsQR.js结果两个实例冲突识别率反而下降。坑五图片带白边或二维码嵌在复杂背景里定位角点被淹没现象二维码是印在纸箱、宣传海报上的背景有纹理或文字。上传后 jsQR 返回 null或者识别出错误的内容。原因jsQR 的定位图案要求周围有足够大的空白区域俗称 quiet zone标准要求至少 4 个模块宽度。复杂背景的纹理和文字会产生伪边缘导致扫描匹配错乱。解决先用 canvas 对二维码区域做裁剪手动把四周扩一圈白边后再传给 jsQR。如果不知道二维码在哪可以先把整个图像做一次高斯模糊再识别但实战更常用的是让用户把二维码尽量对准画面中心做一个人工扫码框。这类问题在摄像头实时扫描时更明显第五章的抽帧策略里我会说一个折中的处理。4.2 调试辅助把灰度图和定位结果可视化遇到识别失败最怕的就是黑匣子式排查。我一般会在页面上临时加一个调试面板把传给 jsQR 之前的 canvas 显示出来人眼能看到的明显问题比如画布空白、图片被裁剪、颜色被反转就都不用来回猜。// 调试把处理后的 canvas 挂到页面上 const debugCanvas document.getElementById(debugCanvas); const debugCtx debugCanvas.getContext(2d); debugCanvas.width imageData.width; debugCanvas.height imageData.height; debugCtx.putImageData(imageData, 0, 0);putImageData和getImageData是互逆操作把 ImageData 原样画到另一个 canvas 上。这一步不经过drawImage所以不会触发 canvas 污染限制。看到画布内容之后再想想是模糊了是反色了还是背景干扰太强比盲试参数高效太多。5. 从静态图片到摄像头getUserMedia 实时扫码与性能调优5.1 摄像头接入getUserMedia 与 video 标签很多实际业务里用户不可能先去拍照再上传要的是打开页面直接扫码。这套例子的思路同样适用只要把图片来源从用户选择文件换成摄像头画面即可。const video document.getElementById(video); async function startCamera() { const stream await navigator.mediaDevices.getUserMedia({ video: { facingMode: environment, width: 1280, height: 720 } }); video.srcObject stream; await video.play(); }facingMode: environment是后置摄像头手机扫码必须用这个否则默认前置摄像头对着用户的脸。width和height决定视频流的分辨率不是越高越好我在 5.3 节单独说。5.2 抽帧循环requestAnimationFrame 里的识别节奏摄像头是连续的视频流但 jsQR 识别一次需要几毫秒到几十毫秒不可能每一帧都识别。常见做法是用requestAnimationFrame循环里加一个节流阀每 N 帧识别一次。let frameCount 0; const FRAME_INTERVAL 5; // 每 5 帧识别一次约 100ms 一次 function scanLoop() { frameCount; if (frameCount % FRAME_INTERVAL 0) { scanFrame(); } requestAnimationFrame(scanLoop); } function scanFrame() { const canvas document.createElement(canvas); canvas.width video.videoWidth; canvas.height video.videoHeight; const ctx canvas.getContext(2d); ctx.drawImage(video, 0, 0); const imageData ctx.getImageData(0, 0, canvas.width, canvas.height); const code jsQR(imageData.data, imageData.width, imageData.height); if (code) { // 识别到就停或者震动提示 navigator.vibrate navigator.vibrate(100); handleResult(code.data); } }FRAME_INTERVAL是节流参数5 帧一次在 30fps 的视频流里就是每 166ms 识别一次。如果识别太频繁CPU 占用高手机会发热太久则二维码从画面中扫过容易漏掉。我一般从 5 起步识别率不够再降到 3发热严重再升到 8。5.3 性能参数分辨率、抽帧频率与识别率的平衡摄像头扫码的性能调优本质是在三项之间找平衡视频分辨率单帧处理耗时识别率设备负载640×480快约 8ms中等近距离码可识别低1280×720中约 15ms高远距离和小时可识别中1920×1080慢约 30ms最高但容易掉帧高经验值是 720p 加 5 帧抽一。1080p 在低端安卓机上单帧处理时间可能超过帧间隔导致requestAnimationFrame堆积画面卡顿。另外可以做一个降级第一次识别失败时把 canvas 区域缩放到原图一半再做一次识别。因为二维码被缩小时相当于做了降采样模糊的影响会被抹平一些对轻微失焦的画面反而有效。// 降采样二次识别把 canvas 宽高各减半减少噪点干扰 const smallCanvas document.createElement(canvas); smallCanvas.width Math.floor(video.videoWidth / 2); smallCanvas.height Math.floor(video.videoHeight / 2); const sCtx smallCanvas.getContext(2d); sCtx.drawImage(video, 0, 0, smallCanvas.width, smallCanvas.height); const sData sCtx.getImageData(0, 0, smallCanvas.width, smallCanvas.height); const code2 jsQR(sData.data, sData.width, sData.height);这个办法在二维码过远、模块密集时效果显著。原理是降采样相当于做了平均滤波把高频噪点抹掉让定位图案的边缘更连续。5.4 扫到结果之后关闭视频流防止摄像头常亮这是新手最容易漏的环节。识别成功后如果直接跳转页面浏览器通常会自动释放摄像头但如果停留在当前页摄像头指示灯一直亮着用户会直接觉得隐私被侵犯。// 识别成功后关闭摄像头 function stopCamera() { if (video.srcObject) { const tracks video.srcObject.getTracks(); tracks.forEach(track track.stop()); video.srcObject null; } }track.stop()是真正关掉摄像头的唯一方法光把video标签隐藏或移除是没用的设备指示灯还亮着。我在做扫码登录页时就是漏了这一步被测试同事当成 bug 报了好几次。6. 封装成一个可复用模块初始化、回调与断流收尾摄像头扫码逻辑如果直接堆在页面里换一个项目就要重写一遍。我习惯把它封装成一个带回调的QrScanner类静态图片识别和摄像头识别共用一套核心。这里给出一个紧凑的封装版本class QrScanner { constructor(videoElement, onDetected) { this.video videoElement; this.onDetected onDetected; this.running false; this.stream null; this.canvas document.createElement(canvas); this.ctx this.canvas.getContext(2d); } start() { this.running true; navigator.mediaDevices.getUserMedia({ video: { facingMode: environment, width: 1280, height: 720 } }).then(stream { this.stream stream; this.video.srcObject stream; this.video.play(); this.loop(); }); } loop() { if (!this.running) return; if (this.video.readyState this.video.HAVE_ENOUGH_DATA) { this.canvas.width this.video.videoWidth; this.canvas.height this.video.videoHeight; this.ctx.drawImage(this.video, 0, 0); const imageData this.ctx.getImageData( 0, 0, this.canvas.width, this.canvas.height ); const code jsQR(imageData.data, imageData.width, imageData.height); if (code) { this.onDetected(code.data); this.stop(); // 扫到即停 return; } } requestAnimationFrame(() this.loop()); } stop() { this.running false; if (this.stream) { this.stream.getTracks().forEach(track track.stop()); this.stream null; this.video.srcObject null; } } } // 页面里使用 const scanner new QrScanner( document.getElementById(video), (result) { alert(扫码结果 result); } ); scanner.start();封装的关键是三个状态start、loop、stop形成一个闭环。loop里执行完一次识别后立即用requestAnimationFrame安排下一次扫到结果或手动stop都会让running变为 false循环自然终止。这样做的好处是调试时能随时从浏览器 console 里敲一句scanner.stop()救场。在真实项目里我会给这个封装再加两个功能一个是识别成功的防抖防止同一码连续触发多次事件另一个是空白帧跳过判断video.readyState和画布内容避免视频还没出画面就跑空循环消耗性能。资源包里的 1.html 和两张测试图本质上是把上面这套逻辑里最核心的静态图片识别那一环拿了出来。你先把 1.html 跑通摄像头扫码就是在它的基础上把图片来源换成视频流而已。从那以后我每次接扫码需求都会强制自己先走一遍这个流程本地文件识别 → 调试面板可视化 → 摄像头接入 → 封装模块四步做完基本不会翻车。希望帮到你。本文还有配套的精品资源点击获取