简介面向 Web 前端开发者的扫码功能集成方案基于 HTML5 与 JavaScript 构建借助 html5-qrcode 库让网页通过摄像头实时识别条形码和二维码常见于电商快速查找商品、移动支付验证、物联网设备配对等需要快捷输入的交互场景。资源共包含 88 个文件压缩包约 9.27MBts 文件提供类型定义和核心业务逻辑js 文件为可直接引用的压缩库md 文档涵盖使用说明、更新日志与示例png/gif/jpeg 则以截图和动图展示扫码效果json/yml 等用于工程配置。目前已有 2127 人学习下载。包内除了完整源码还保留了测试用例、React/Vue/Electron 等框架接入示例并附有从权限申请到停止扫描的完整调用说明以及浏览器兼容性、性能优化与安全处理等方面的注意事项开发者只需引入库并调用扫描接口即可完成集成同时也能按需修改源码进行定制。1. 扫一扫条形码和二维码的 H5 插件专治扫码枪不在手边做后台系统久了总会撞上这类需求仓库盘点单上要扫一串条码参会签到要扫二维码设备巡检要记机身编码。要么配一把扫码枪要么让用户掏出手机对着屏幕拍一是硬件不在手边二是第三方 App 的扫码能力绑死了域名校验和回调逻辑换到自研 WebView 往往白屏。这份“扫一扫条形码和二维码的 H5 插件”就是一个纯前端方案用 htmljs 调起摄像头原生检测 API 优先、纯 JS 识别库兜底同一套代码能同时识别二维码和主流的商品条形码不依赖任何平台 SDK。适合集成进后台管理系统、移动端 App 内嵌页和临时用的工具站。下文会拆解选型理由、完整代码与真机排错。2. 选型拆解为什么是“原生检测 API 纯 JS 识别库”双引擎2.1 先排除两条“看起来省事”的路在动手之前先把市面上常见的方案过一遍避免从立项开始就踩坑。第一个是依赖宿主 App 自带的扫码能力。这类能力的优点是识别率稳定后台封装好了但问题是基本都需要域名校验、权限申请、回调地址配置而且只在特定的 WebView 环境里生效。也就是说同一段逻辑换到桌面浏览器、换到别的 WebView 容器就要整套重写。对只想做一个“网页扫码”的团队来说隐藏成本比看起来高得多。第二个是直接外接扫码枪。扫码枪在桌面端本质是一个 HID 键盘输入设备把条码数字模拟成键盘敲进去优势是无感、快、免开发学习成本。但它的短板同样明显只能识别条码类内容二维码里嵌的网址、Wi-Fi 配置、JSON 文本这类结构化数据拿不到输入事件必须有一个窗口实时接收焦点否则按键会被打散到页面各处移动端更不可能靠 USB 外接。而这个插件的目标场景是手机、平板、桌面浏览器都跑扫码枪第一条就被排除。第三个要排除的思路是“全走服务端识别”。把每一帧上传到后端解析确实能解模糊码、复杂码但要自己搭图片上传接口、处理并发、考虑存储与带宽还会引入隐私合规问题。对于仓储、巡检这类真实业务摄像头画面本身不能随便出设备纯前端识别反而是更稳妥的合规选择。2.2 双引擎策略主用原生 BarcodeDetector缺了就降级回到纯前端方案。识别引擎大致有三类原生 BarcodeDetector API、纯 JS 识别库、服务端识别。把三个方向的特性摆在一张表里看比较直观。方案部署方式实时性离线能力跨端一致性主要风险原生 BarcodeDetector API浏览器内置最快完全离线只有 Chromium 内核支持完整非主流内核直接不可用纯 JS 识别库jsQR 等引一个 JS 文件中等逐像素扫描完全离线跨内核一致但耗时有差异分辨率低时识别率骤降服务端识别搭接口 存储受网络影响不具备一致带宽、隐私、故障点清点下来主用 BarcodeDetector、缺了就降级到 jsQR 是这套插件里最稳的组合。原生路径跑在 Chromium 内核的桌面浏览器和大多数 Android WebView 上能直接对视频流调用detect()返回条码内容、位置和尺寸速度快而且不需要引任何依赖降级路径跑在 iOS 自带浏览器、桌面 Firefox 这类不支持原生 API 的环境里把当前帧画到离屏 canvas 上交给 jsQR 逐像素解析。双引擎在外观上没有差异业务方只消费同一个回调事件不用感知底层走的是哪条路。还有一个细节BarcodeDetector 构造时传入的格式列表不能想当然全给。不同内核实现支持的格式不完全一致比如某些发行版对ITF、Codabar支持不全直接传入会在构造函数就抛异常。所以插件里把构造过程包进 try-catch一旦构造失败立即整体降级到 jsQR绝不会因为格式列表问题把两条路都堵死。到底支持哪些格式我在插件里按这几类配置二维码格式qr_code商品零售最常见的一维码ean_13、ean_8、upc_a、upc_e仓储物流常用的code_128、code_39、itf。这套组合覆盖了线下业务里 95% 以上的扫码场景。2.3 权限链路为什么摄像头一定要走 getUserMedia纯前端扫码绕不开摄像头访问这里必须理解授权链路否则在真机上调试十有八九会遇到“白屏一会儿然后拒绝”的尴尬。navigator.mediaDevices.getUserMedia的流程是浏览器先检查当前页面是否是安全上下文HTTPS 或 localhost再检查页面是否有 camera 权限Permissions-Policy最后弹授权框询问用户。任何一环被卡住返回的 Promise 都会 reject而且错误类型还不一样NotAllowedError用户拒绝了授权或页面不在安全上下文NotFoundError设备上没有任何可用摄像头NotReadableError摄像头正被其他程序占用OverconstrainedError设置的约束参数在当前设备上无法满足SecurityError页面不允许调用媒体设备 API。插件在打开摄像头之前先做一次环境预检把“非 HTTPS”这种基础问题提前暴露出来而不是等用户授权后才失败const isSecure window.isSecureContext || location.hostname localhost || location.hostname [::1]; if (!isSecure) { showToast(请先通过 HTTPS 访问本页面); return; }逻辑说明isSecureContext是浏览器提供的最可靠判断方式localhost和 IPv6 回环地址[::1]是开发环境的豁免项允许本地联调。这段预检放在页面加载时跑一次能提前拦截掉一半以上的部署环境问题剩下的一半在 getUserMedia 的错误分支里兜住详见第 4 章。理解这条链路还有个实际收益getUserMedia必须在用户手势里触发比如按钮 click 的回调内。如果页面一加载就自调用多数桌面浏览器会直接把 Promise reject 掉。这也是很多开发者第一次把扫码模块嵌进管理系统时遇到“明明授权过还是打不开”的根源之一。代码层我把“获取视频流”和“启动识别循环”拆成两个函数由按钮事件驱动式调用下面第 3 章会给出具体写法。3. 核心实现摄像头帧循环、双引擎识别与参数调优3.1 页面骨架扫码框、视频层和隐藏画布搭建页面需要三个关键元素video展示摄像头预览画面离屏canvas截取当前帧交给识别引擎页面上再用一个带边框的扫码框做视觉引导。扫码框不参与裁剪逻辑它的作用是提示用户“把码对准这个区域”这个设计在参数调优时会让思路清爽很多。div idscanner-panel video idvideo playsinline muted/video div idscan-overlay/div /div canvas idframe-buffer styledisplay:none;/canvas button idstart-btn typebutton打开摄像头扫码/button参数说明video上的playsinline和muted是移动端浏览器能够自动播放画面的前提少了playsinline会出现画面出来但一直黑屏的诡异现象muted是因为自动播放策略会拦截带声音的视频流。scan-overlay用 CSS 画一个四角边框即可不需要任何图片素材。3.2 打开摄像头约束参数与视频流获取let stream null; const videoEl document.getElementById(video); async function openCamera() { if (stream) { stream.getTracks().forEach(track track.stop()); } const constraints { audio: false, video: { facingMode: { ideal: environment }, width: { ideal: 1280 }, height: { ideal: 720 } } }; try { stream await navigator.mediaDevices.getUserMedia(constraints); videoEl.srcObject stream; await videoEl.play(); startScanLoop(); } catch (err) { handleCameraError(err); } } document.getElementById(start-btn).addEventListener(click, openCamera);逻辑说明openCamera先停掉上一次残留的流避免重复打开时摄像头被占用。constraints里facingMode: { ideal: environment }表示优先调用后置摄像头注意这里用的是ideal而不是exact在只有前置摄像头的设备上浏览器会退而选择可用摄像头不会直接抛OverconstrainedError。width和height同样用ideal软约束让浏览器尽量靠近 1280x720 这个分辨率又不至于在低端设备上报错。有一个顺序细节拿到srcObject之后必须立即video.play()。不少实现漏掉这一步画面停留在第一帧黑屏识别循环却一直在空转。play()必须在srcObject赋值之后调用顺序反了同样会黑屏。3.3 识别循环原生先行降级兜底let scanTimer null; let lastResult ; let lastTry 0; function startScanLoop() { const engine detectEngine(); const tick () { scanTimer requestAnimationFrame(tick); // 限频识别耗时高不能每帧都跑 if (Date.now() - lastTry 100) return; lastTry Date.now(); recognizeFrame(engine); }; tick(); }逻辑说明startScanLoop开启一个 rAF 循环但识别本身很耗主线程我在循环内部做一道时间闸门把识别频率压到每秒约 10 次。参数100毫秒是速度与负载的折中高速流水线场景可降到 80弱机或低功耗场景可调到 150 到 200。限频除了省电还顺带解决了原生detect()返回 Promise 带来的并发问题——上一次还没 resolve下一次又发出去会产生不可控的竞态。detectEngine()负责判断环境并构造对应的引擎实例function detectEngine() { if (BarcodeDetector in window) { try { return { name: native, detector: new BarcodeDetector({ formats: [ qr_code, ean_13, ean_8, code_128, code_39, upc_a, upc_e, itf ] }) }; } catch (e) { // 某些浏览器只支持部分格式构造失败时降级 } } return { name: jsqr }; }参数说明format 列表覆盖了商品零售和物流场景最常见的条码格式。核心技巧是把构造过程包进 try-catch部分内核的 BarcodeDetector 不支持itf构造函数直接抛异常这时候自动降级到 jsQR不会把两条路都堵死。真正的识别分叉放在recognizeFrame里async function recognizeFrame(engine) { const result engine.name native ? await detectNative(engine.detector) : await detectWithJsqr(); if (!result) return; if (result lastResult) return; lastResult result; document.dispatchEvent(new CustomEvent(scan-success, { detail: result })); }async function detectNative(detector) { const codes await detector.detect(videoEl); return codes.length ? codes[0].rawValue : null; }async function detectWithJsqr() { const canvas document.getElementById(frame-buffer); const ctx canvas.getContext(2d); // 只分析扫码框覆盖的中央区域降低像素量 canvas.width 480; canvas.height 360; ctx.drawImage(videoEl, 0, 0, canvas.width, canvas.height); const imageData ctx.getImageData(0, 0, canvas.width, canvas.height); const code jsQR(imageData.data, imageData.width, imageData.height, { inversionAttempts: dontInvert }); return code ? code.data : null; }这段值得展开。原生路径直接把video元素交给detect()由浏览器内部识别性能最好。但detect返回的是 Promise如果在 rAF 循环里连续调用上一次没 resolve 下一次又发出去会有微妙的竞态这也是前面那个 100 毫秒限频存在的直接原因。jsQR 路径的关键是canvas.width、canvas.height和getImageData的宽高必须一致否则 jsQR 解析的像素矩阵是错位的。我习惯把画布缩到 480x360 而不是直接按视频原始尺寸取帧因为 jsQR 的处理复杂度跟像素量成正比缩小后再扫速度能快三到五倍。inversionAttempts: dontInvert是另一个提速点jsQR 默认会尝试黑白反转以识别反色码但耗时几乎翻倍。常态条码环境建议关掉等到确实遇到黑底白码再单独开启。lastResult做的是同码去重。扫码场景里用户习惯“拿着手机一晃”如果不做去重同一帧命中十几次回调就会被触发十几次后台会出现大量重复记录。更完整的“冷却时间 结果确认”组合留到第 6 章讲。3.4 手动输入兜底摄像头之外的保险识别循环再稳也总会有兜不住的场景摄像头被禁用、条码磨损、灯光直射反光。页面必须提供手动输入入口否则用户只能干瞪眼。const manualInput document.getElementById(manual-input); manualInput.addEventListener(keydown, (e) { if (e.key ! Enter || !manualInput.value.trim()) return; document.dispatchEvent(new CustomEvent(scan-success, { detail: manualInput.value.trim() })); manualInput.value ; closeScanner(); });逻辑说明手动输入框的事件放在扫瞄器组件自己的作用域里不要跟全局表单的 submit 逻辑混在一起否则扫码页嵌入大表单时会莫名触发整页提交。Enter 触发回调后立即关闭扫码层与扫码成功后的收尾动作保持一致代码路径统一后续维护省很多事。4. 兼容性兜底HTTPS、iframe 权限与移动端 WebView 差异4.1 HTTPS 是硬前提只有 localhost 能豁免前端扫码模块上线后最容易翻车的一步不是代码而是部署环境。getUserMedia要求页面运行在安全上下文里普通 HTTP 站点直接被浏览器拒绝授权错误码是NotAllowedError但原因不是用户点了“禁止”而是浏览器压根没给弹窗。这个坑在本地开发时往往不暴露因为localhost本身被浏览器视为安全上下文。于是常见剧本是本地联调一切正常丢到测试服、生产服之后摄像头就再也打不开了。排查顺序应该是先看地址栏是不是 HTTPS再看证书有没有过期最后才回到代码层怀疑授权逻辑。部署后的另一隐患是旧缓存。很多管理系统做了 Service Worker 离线缓存扫码功能上线后用户浏览器还在跑旧 JS新权限逻辑没生效现象就是“明明线上版本更新了扫码还是坏的”。这种场景下要让发布流程带上版本号查询参数强制刷新缓存例如scanner.js?v20250115。我在插件 README 里把这两条写在了第一页部署前强制自查。4.2 iframe 嵌入使用权限策略控制而非代码 hack中后台系统经常把扫码器嵌进 iframe 里这时摄像头权限不是一个“全局开关”而是受 Permissions-Policy 头控制的。外层页面响应头里如果没有放行camera内层 iframe 即使代码完全正确也会在授权阶段被拒。后端响应头示例Permissions-Policy: camera(self https://scan-host.example.com)说明self表示页面自身可以使用摄像头能力后面的字符串表示允许指定的子域名通过 iframe 使用摄像头。如果中后台的扫码页和主系统不同域必须在主系统响应头里把这个域名加进去。很多开发者以为问题出在前端反复改 iframe 的allow属性其实allowcamera只是前端声明后端不配 Permissions-Policy 照样没用。另一个做法是 iframe 上保留allowcamera双管齐下。前端和后端两个位置都要对上缺一个都会导致沙箱环境里摄像头静默失联。调试时先打开 iframe 的独立地址验证摄像头权限是否正常再回到嵌出页面验证策略头是否生效能快速二分定位。4.3 iOS 自带浏览器与 Android WebView两套完全不同的脾气移动端是扫码的主战场但移动端的坑比桌面端多一个量级。iOS 自带浏览器里playsinline没写的话视频会强制进入全屏播放模式扫码框和按钮全部被盖住交互直接废掉。另外首次调用 getUserMedia 时会弹授权用户一旦选了“仅一次”第二次打开页面又会重新弹业务上需要接受这个行为不要试图绕过。还有一个很容易被忽视的问题页面切到后台再回前台旧的视频流经常变成黑帧需要监听visibilitychange事件回到前台时重新获取流并重启识别循环而不是复用旧流。插件的ensureCameraReady()就是为这个场景设计的扫码按钮点击和页面回前台两个入口都走它。Android 端的 WebView 要单独说。系统 WebView 的摄像头授权弹窗由宿主 App 托管如果宿主 App 没有在系统层面声明 CAMERA 权限内嵌页调 getUserMedia 会走失败分支而且不同系统版本返回的错误文案还不一样。排查时优先确认宿主 App 的权限声明而不是盯着页面代码反复改。部分老版本的 Android WebView 对facingMode: { ideal: environment }解析不完全会直接选用前置摄像头识别距离就完全不对了。插件里带了一个设备信息探测函数在扫码前把摄像头列表枚举一遍把实际选中的方向显示在调试面板上这一步对真机适配帮助很大。遇到前置后置错乱的老设备可以临时加一条约束优先取第一个非前置的摄像头 track绕开 facingMode 的解析缺陷。4.4 异常分支权限拒绝、无摄像头和应用占用不管用户是被吓到点了拒绝还是设备实在没有摄像头页面都不应该停留在“无反应”状态。function handleCameraError(err) { const map { NotAllowedError: 摄像头权限未开启请在浏览器设置中允许访问, NotFoundError: 未检测到摄像头设备, NotReadableError: 摄像头被其他程序占用请关闭其他应用后重试, OverconstrainedError: 当前设备不满足视频约束请换一台设备尝试 }; const msg map[err.name] || 摄像头打开失败请手动输入条码; showToast(msg); manualPanel.classList.remove(hidden); }逻辑说明错误分支不仅要有提示文案还要把手动输入面板同时暴露出来。移动端用户对“扫码失败”几乎零耐心一个能手动输入的入口能兜住大量真实投诉。OverconstrainedError在桌面端很少见但在只有低端摄像头的设备上出现过提示语要口语化不要直接把错误名甩给用户。对于NotReadableError这类偶发问题我还加了一次自动重试记录错误发生后 3 秒未成功就自动再次调用openCamera()重试次数限制为 1避免无限循环。实践下来摄像头被其他 App 短暂占用的情况一次重试往往就能恢复。5. 避坑记录扫一扫 H5 最常见的五个黑匣子问题5.1 摄像头能打开但二维码怎么都扫不出来现象视频画面正常、扫码框也在可无论怎么移动手机结果一直为空日志里也没有报错。原因两层。一是默认视频分辨率太低浏览器通常只给 640x480小码或远距离二维码在图像上只有几十个像素任何识别引擎都无能为力二是扫码框视觉上很大但识别引擎扫的是全帧缩略图码稍微偏一点就超出计算区域。解决把width/height约束提到 1280x720并把 canvas 裁切到画面中心区域让识别引擎只分析框内画面即第 3.3 节里的 480x360 缩略帧。建议再多做一步把视频元素与 canvas 的坐标对齐扫码框对应 canvas 的哪一块区域写死在配置里不要在视觉布局变化后再去猜。碰到顶灯反光的场景临时把inversionAttempts改为attemptBoth反色码也能接住。5.2 jsQR 抛错“imageData.data is undefined”现象降级到 jsQR 后控制台直接抛异常扫码中断。原因最常见的是 canvas 的宽高属性没设置getImageData返回的全是零矩阵另一种是canvas.width改过但ctx.drawImage用了视频原始尺寸和scan传入的宽高不一致像素矩阵错位。这个报错不是 jsQR 本身的问题而是画布用法没对齐。解决把canvas.width、canvas.height、drawImage的目标尺寸、getImageData(0, 0, w, h)、jsQR 的扫描宽高全部写成同一组常量不要各自使用不同数值。插件里这组常量集中在SCAN_GEOMETRY配置对象里改一次全局生效。调试时把隐藏 canvas 暂时显示出来肉眼对照取帧区域和扫码框是否一致能直观发现问题。5.3 iOS 上扫码成功后第二次黑屏现象第一次扫码正常回调也触发了但用户回到扫码页再次使用画面是黑的只有按钮还在。原因页面切后台或者被系统压入后台后视频流处于中断状态重新回到前台时没有重新初始化。iOS 对后台视频流的处理尤其严格旧的MediaStreamTrack基本不可靠必须重建。解决监听visibilitychange页面重新可见时先stop掉旧流的所有 track再完整走一次openCamera()。不要图省事直接复用stream变量一定要走完整的先停后开。插件把这个过程封装在ensureCameraReady()里扫码按钮点击和页面回前台两个入口都调用它保证路径唯一。5.4 Android 真机授权通过了却还是返回 NotAllowedError现象授权弹窗点了允许但 Promise 依然 reject错误码是 NotAllowedError完全不按常理出牌。原因一个可能是宿主 App 没在系统层面声明相机权限WebView 的权限请求到了系统层就被拦截浏览器层拿到的是“同意”系统返回的是“拒绝”另一个可能是某些国产品牌的 ROM 在授予 WebView 权限后还需要单独给宿主 App 开启“后台弹出界面”权限不过这种情况相对少见。解决先在系统设置里手动给宿主 App 授予相机权限再重新打开扫码页。如果还不行就检查宿主 App 的权限配置里 CAMERA 声明是否齐全这一步通常需要客户端同事配合。真机调试时优先用系统浏览器而不是内置 WebView可以快速隔离是页面问题还是宿主问题。5.5 原生检测引擎在弱机上导致掉帧、页面卡顿现象用了 BarcodeDetector 之后扫码画面正常但整个页面开始掉帧尤其是列表页和弹窗动画明显变卡。原因原生检测器虽然性能比纯 JS 好但它在主线程上跑逐帧调用detect()会占据大量主线程时间片。加上页面本身有 DOM 更新两者挤在一起卡顿就被放大了。解决把识别频率限到每秒 8 到 10 次同时把detect的结果交给setTimeout0 处理避免每帧都在主线程排队。更进一步把耗时的识别逻辑塞进requestIdleCallback里让浏览器在空闲时再干活。总体上限频对识别率的影响可以忽略但对页面流畅度的提升非常明显。生产环境里我会留一个可调参数SCAN_INTERVAL_MS弱机上调到 150桌面端可维持在 80。6. 进阶与验证多码场景、命中率自查与防重复收尾多码场景是把“能扫出来”往前推一步的关键。外包装上经常同时贴了商品条码和物流二维码用户瞄准哪一个都能触发回调。原生引擎会一次返回多个码但业务层通常只需要一个值我倾向于取第一个并忽略剩余结果如果是“批量扫描盘点”需求则可以把结果数组逐条透传给上层关键是在回调里保留rawValue的同时也保留boundingBox方便页面高亮告知用户命中了哪一个区域。jsQR 一次只能解一个码处理多码时就需要对画布分区域多次调用或者接受“同一时刻只扫一个码”的物理限制我的默认策略是后者多数业务够用。命中率自查建议用三组真实样本打印的条码、屏幕上的二维码、折叠过的纸箱码。每组扫 30 次统计首次识别耗时和成功率。我通常拿一个秒表 App 记录从对准到回调的延迟原生引擎稳定在 150 毫秒内jsQR 路径在 480x360 画布下约 300 到 500 毫秒哪一条超过这个量级就去检查限频参数和分辨率设置。防重复是最容易被低估的细节。扫码成功后的 600 毫秒内如果不加冷却用户手指一抖可能连续触发三四次扫码事件后台会收到好几条重复记录。我的做法是扫描结果先经过一层“结果确认 冷却时间”管线命中后置一个 800 毫秒的冷却窗口窗口内任何识别结果都被丢弃同时用 Web Audio 现场合成一个 1000Hz、200 毫秒的蜂鸣让用户明确知道已经成功。这个蜂鸣不依赖任何音频文件离线单页面也能正常工作。插件里识别循环、结果防抖、蜂鸣提示、手动输入四条路径都统一到一个控制类里业务方只要监听scan-success事件拿到最终字符串即可不需要感知引擎差异。我记得第一次给客户的签到系统做扫码模块就是在防重复上翻的车——后台导出的签到名单里出现了大量重复记录排查了很久才定位到是扫码回调被触发了多次。从那以后我每次做前端扫码都会强制走一遍“双引擎降级 限频 结果去重”这条链路先在三种真实样本上验证再交出去。希望这份资源能在你接入扫一扫时少绕几个弯子。本文还有配套的精品资源点击获取