简介：这是一份纯HTML+JS实现的条形码识别前端方案，面向需要快速集成扫码功能、又不想引入后端服务或复杂框架的Web开发者（如本地工具、轻量管理页面、移动端H5）。压缩包共11个文件，包含5个JavaScript脚本、4个HTML页面和2个Markdown说明文档，整体体积仅90KB；其中JS承担条形码解析与图像处理逻辑，HTML页面提供多档演示入口，Markdown文档便于查看使用说明。资源提供从最简单的单页演示到进阶版视频识别、图片上传识别等多档实现，并对识别准确度做了专门优化，可满足实时扫码与离线识别两类典型场景。目前已有767人学习下载，配套说明对代码组织和使用方式做了梳理，帮助开发者快速理解条形码识别从前端调用到图像处理的完整链路，同时为改造适配提供可参考的基线版本。
1. 纯 HTML+JS 实现条形码识别，核心不在算法而在浏览器能力
纯 HTML+JS 实现条形码识别，很多人第一反应是必须接扫码枪或者搬出 OpenCV.js。实际上在 Chrome/Edge 体系里，浏览器原生 API BarcodeDetector 已经把"从摄像头画面找条码、解出内容"两步一起做完，一两百行代码就能做出免后端、免插件的扫码页。这类 zip 解压后通常就是单个 html 加一个脚本文件，没有 npm install、没有构建步骤。它适合 Web POS、资产盘点 H5、条码录入工具页。真正花时间的不是识别那一行调用，而是浏览器支持矩阵、帧率节流、坐标对齐这三个边界问题，下文按原理、Demo、降级、调优四层展开。
2. 条形码识别在前端的三种落地方式：BarcodeDetector、ZXing 与手写解码
纯前端读条形码，业界常见做法是三条路：优先用浏览器内置的 BarcodeDetector；它不可用时降级到 ZXing 的 JS 移植版；最后一条"自己写解码器"只适合学习，不建议上生产。先别急着写代码，把三条路的边界弄清楚，后面排错会省一半时间。
2.1 BarcodeDetector 把定位与解码封装成一个黑盒
BarcodeDetector 属于 Barcode Detection API，目前还在草案阶段。调用detect(imageSource)时，传入 HTMLVideoElement、HTMLCanvasElement、ImageData 或 ImageBitmap 都可以，返回的 Promise 会 resolve 成一个数组，数组里每个元素是一次识别结果：format是条码类型（如 ean_13、code_128、qr_code），rawValue是解出来的字符串，boundingBox是探测到的矩形区域，cornerPoints是四个角的坐标点。浏览器内部完成的工作实际是两段：先在画面里做定位，找到疑似条码的高对比条纹区域；再对定位区域按对应码制的编码表逐段解码，EAN-13 的 13 位数字带校验位，Code 128 带 mod 103 校验，解码器会顺手做掉这一步，读错的情况比想象中少。
黑盒的代价是行为随平台漂移。在 Android 的 Chrome 里，底层通常走系统机器学习组件，模糊、倾斜、反光都有不错的容错；在 Windows 桌面 Chrome 上，格式支持和识别率就和移动端不完全一样。所以正经项目一般不会只写死new BarcodeDetector()，而是在启动时先用getSupportedFormats()探一次底。
2.2 为什么还要留一条 ZXing 降级路径
ZXing 是 Java 生态里最老牌的开源条码解码库之一，JS 移植版用纯 TypeScript 实现，不需要 WebAssembly，一个 script 标签就能引入。它的解码能力和原生 API 比不差，弱点在速度和体积：单帧解码耗时普遍要几十毫秒到一百多毫秒，打包体积也明显更大。但它是 Firefox、iOS Safari 这些拿不到 BarcodeDetector 的环境里最稳的一条路。三条路放一起对比如下：
| 方案 | 依赖 | 格式覆盖 | 单帧耗时 | 适用场景 |
|---|---|---|---|---|
| BarcodeDetector | 浏览器内置 | EAN/UPC/Code 128/39/QR/Data Matrix/PDF417 等 | 原生级，通常 10~50ms | Chrome/Edge 为主的内部系统、Android WebView |
| ZXing JS | 需引入脚本 | 一维码为主，QR 单独 Reader | 纯 JS，50~150ms 常见 | Firefox/iOS Safari 降级、WebView 兼容层 |
| 自研解码器 | 无 | — | — | 学习用途，生产不建议 |
上表是"常见做法"的概括，不是定论。格式覆盖在不同版本、不同平台上一直在增减，上线前要用目标设备实测一遍再定策略。
2.3 先用 getSupportedFormats 探底，别把 formats 写死
这里给出最廉价的一个验证步骤：在目标浏览器控制台里跑下面这段，把它输出的数组存档，作为兼容性依据。
if ('BarcodeDetector' in window) { BarcodeDetector.getSupportedFormats() .then((formats) => console.log('本浏览器支持的条码格式：', formats)) .catch((err) => console.warn('格式查询失败：', err)); } else { console.log('当前浏览器没有 BarcodeDetector，需要降级方案'); }getSupportedFormats()是静态方法，不需要先 new 实例；它返回的格式名就是小写下划线风格，和后面new BarcodeDetector({ formats: [...] })里要传的值一一对应。常见差异是：Android 端格式列表通常比桌面端全，某些桌面 Chrome 版本甚至只暴露 QR 和几种一维码；Firefox 与 iOS Safari 目前默认不向网页暴露这个 API。所以代码里凡是写死formats的地方，都应该先和这个探底结果取交集。
3. 用 getUserMedia + BarcodeDetector 跑通最小识别页面
这一部分直接给一份可以保存为.html文件运行的完整代码，整个页面就是<video>、<canvas>加一个识别循环。建议按"先动起来、再优化"的顺序来，先把摄像头、识别、画框三条链路都跑通，再谈帧率和裁剪。
3.1 页面骨架：video、canvas 和摄像头参数
<!DOCTYPE html> <html lang="zh-cn"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>纯 HTML+JS 条形码识别 Demo</title> <style> #view { position: relative; display: inline-block; } video { display: block; width: 640px; } #overlay { position: absolute; left: 0; top: 0; width: 640px; height: 360px; } </style> </head> <body> <h3>把条码对准镜头</h3> <div id="view"> <video id="video" autoplay playsinline muted></video> <canvas id="overlay"></canvas> </div> <p>识别结果：<span id="result">等待中…</span></p> <script> const video = document.getElementById('video'); const overlay = document.getElementById('overlay'); const ctx = overlay.getContext('2d'); const resultEl = document.getElementById('result'); const detector = new BarcodeDetector({ formats: ['ean_13', 'ean_8', 'upc_a', 'code_128', 'code_39', 'qr_code'] }); async function start() { const stream = await navigator.mediaDevices.getUserMedia({ audio: false, video: { facingMode: { ideal: 'environment' }, width: { ideal: 1280 }, height: { ideal: 720 } } }); video.srcObject = stream; await video.play(); overlay.width = video.videoWidth; overlay.height = video.videoHeight; requestAnimationFrame(scan); } let lastScanAt = 0; const SCAN_INTERVAL = 100; async function scan(timestamp) { if (video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA && timestamp - lastScanAt >= SCAN_INTERVAL) { lastScanAt = timestamp; try { const codes = await detector.detect(video); drawResult(codes); } catch (err) { console.warn(err); } } requestAnimationFrame(scan); } function drawResult(codes) { ctx.clearRect(0, 0, overlay.width, overlay.height); if (!codes.length) return; const code = codes[0]; const box = code.boundingBox; ctx.strokeStyle = '#00c853'; ctx.lineWidth = 3; ctx.strokeRect(box.x, box.y, box.width, box.height); ctx.fillStyle = '#00c853'; ctx.font = '13px monospace'; ctx.fillText(`${code.format} ${code.rawValue}`, box.x + 4, box.y - 6); resultEl.textContent = `${code.format} : ${code.rawValue}`; } start().catch((err) => { resultEl.textContent = '摄像头打开失败: ' + err.name + ' ' + err.message; }); </script> </body> </html>把这页在 localhost 或任意 HTTPS 域名下打开，授权摄像头后把 EAN-13 商品码或任意 Code 128 条码放进画面，识别框和字符串会在 100ms 内出现。几个关键参数逐个说：
playsinline和muted：iOS Safari 下 video 不带 playsinline 会被强制全屏，autoplay 也会被媒体策略拦掉；静音视频更容易通过自动播放检查。facingMode: { ideal: 'environment' }：告诉浏览器优先选后置摄像头。ideal 是"尽量满足、不行就换"；想强制后置要写{ exact: 'environment' }，代价是设备只有前摄时直接抛 NotFoundError。width/height用 ideal：浏览器会按摄像头能力集协商出最接近的分辨率，写死固定值反而可能触发降采样，画面变糊。1280×720 是解码耗时的性价比分水岭，更高分辨率并不会显著提升一维码识别率。
3.2 识别循环用 rAF 节流，不要每帧都 detect
上面代码里scan用 requestAnimationFrame 驱动，但真正调用 detect 之前做了两道闸：readyState >= HAVE_CURRENT_DATA保证视频已经渲染出帧，timestamp - lastScanAt >= SCAN_INTERVAL把识别频率限制在约 10fps。BarcodeDetector 的 detect 在复杂画面上可能耗时几十毫秒，如果每帧都去 await 一次，Promise 会排队，主线程被拖住，画面直接卡成幻灯片。扫码场景 10fps 完全够用，人手的移动速度在 100ms 窗口内不会造成太大模糊。
这里补充一个容易踩的坑：直接detector.detect(video)在视频没有准备好时会被拒绝，错误类型各家实现不统一，所以 try/catch 不能省。更稳的写法是每次先 drawImage 到离屏 canvas 再 detect 那张 canvas，但第一版直接传 video 性能更好，失败概率也低，先这么用。
3.3 overlay 画布尺寸必须和视频源对齐
CSS 里#overlay的宽高写的是 640×360，与width: 640px的 video 视觉上对齐；但 JS 里真正起作用的赋值是overlay.width = video.videoWidth，这是画布的内部像素尺寸。boundingBox.x/y是视频源像素坐标系（比如 1920×1080）里的值，如果画布内部尺寸和设备实际分辨率不一致，识别框就会整体偏移。把两者都设成 videoWidth/videoHeight，再让 CSS 去缩放显示，是最不容易出错的做法。
| getUserMedia 约束 | 行为 |
|---|---|
facingMode: 'environment' | 优先后置，无则回退 |
facingMode: { exact: 'environment' } | 强制后置，不满足抛 NotFoundError |
width: { ideal: 1280 } | 协商逼近，不保证 |
width: { min: 640, ideal: 1280, max: 1920 } | 范围约束，浏览器选能力集 |
提示：getUserMedia 只在安全上下文可用，localhost 和 HTTPS 可以，直接双击 file:// 打开通常会被拒绝。
4. Firefox 和 iOS 上拿不到 BarcodeDetector 时的 ZXing 降级
兼容性问题的标准解法是特性检测后走两条链路。判定条件不要只看'BarcodeDetector' in window，还要看业务必须的格式在不在getSupportedFormats()结果里。
4.1 特性检测与双链路切换的判定逻辑
async function pickDecoder() { const hasNative = 'BarcodeDetector' in window; let available = []; if (hasNative) { available = await BarcodeDetector.getSupportedFormats(); } const required = ['ean_13', 'ean_8', 'upc_a', 'upc_e', 'code_128', 'qr_code']; const enough = required.every((fmt) => available.includes(fmt)); if (hasNative && enough) { startNativeDetector(); // 走第 3 章的方案 } else { startZxingDecoder(); // 走 4.2 的降级方案 } }required.every(...)是数组的 every 方法，逻辑是"业务要求的所有格式，当前环境必须全部支持，缺一个都算不达标"。历史上遇到过桌面 Chrome 只支持 QR 不支持一维码的情况，只判断in window会直接走进一条跑不起来的原生链路，所以格式列表的交集检查必须做。
4.2 ZXing 连续识别的调用与停止
引入方式按工程习惯来：构建工程用import { BrowserBarcodeReader } from '@zxing/browser'，静态页面用 script 标签引入 UMD 构建。引入后全局会暴露ZXing命名空间，用下面这段启动连续识别：
const hints = new Map(); hints.set(ZXing.DecodeHintType.TRY_HARDER, true); hints.set(ZXing.DecodeHintType.POSSIBLE_FORMATS, [ ZXing.BarcodeFormat.EAN_13, ZXing.BarcodeFormat.CODE_128, ZXing.BarcodeFormat.QR_CODE ]); const reader = new ZXing.BrowserBarcodeReader(hints); const controls = reader.decodeFromVideoDevice(video, (result, error) => { if (result) { onDecoded(result.getText()); } // error 表示"这一帧没解出内容"，属于正常回调，不要当作异常处理 }); // 页面卸载或用户离开扫码页时释放资源 // controls.stop();decodeFromVideoDevice内部用定时器不断抓视频帧做解码，识别到内容时第一个回调参数是 Result 对象，getText()拿字符串，getBarcodeFormat()拿格式；没识别到时第二个参数会有值，这是正常的空扫描反馈。注意不同版本的构造器签名不一样，老版本直接传 hints Map，新版本构造函数第一个参数变成 Reader 实例，具体以你锁定的 package 版本的类型声明为准，别照抄旧博客。另一个常被提到的库是 jsQR，它只做二维码；如果标题里的"条形码"主要是 EAN/Code 128 这类一维码，ZXing 更对口。
一维码和二维码都要的话，老版本需要分别用BrowserBarcodeReader和BrowserQRCodeReader两个实例，新版本可以直接用 MultiFormatReader 统一处理。controls.stop()返回控制器对象，在页面卸载或路由切换时调用，避免后台继续抢摄像头。
4.3 ZXing 两个 hint 的取舍与常见错误
TRY_HARDER的含义是允许解码器在模糊、倾斜、低对比度的帧上花更多时间去穷举，代价是单帧耗时上升、误报率也略微变高；摄像头实时扫码建议打开，但要配合POSSIBLE_FORMATS把候选格式收窄，否则解码器会对每一帧都尝试所有格式组合。POSSIBLE_FORMATS直接决定每帧要跑几种定位模式和校验表，能显著缩短耗时。反过来，PURE_BARCODE这个 hint 不要设，它假设画面里只有条码没有背景，真实摄像头画面几乎不会满足，设置了反而让大部分帧直接判失败。
ZXing 链路里最常见的三类报错都出在摄像头这一层：
| 错误名 | 触发原因 | 处理建议 |
|---|---|---|
| NotAllowedError | 用户拒绝授权，或页面不是安全上下文 | 引导用户到地址栏重置摄像头权限 |
| NotFoundError | 设备上没有可用摄像头 | 隐藏扫码入口，降级为图片上传识别 |
| NotReadableError | 摄像头被其它应用或另一个标签页占用 | 提示关闭占用方后点击重试 |
ZXing 对图像分辨率的敏感度和原生 API 不一样，1280×720 下单帧耗时可能到一百毫秒以上。降级链路里可以把传入的视频帧先缩到 640×360 再交给 reader，速度提升明显，但前提是条码最窄的竖条在缩采样后仍然有 2 个像素以上宽度，否则怎么调 hint 都解不出来。
5. 上线前必调的三处：ROI 裁剪、连续帧确认与格式白名单
链路跑通只是开始，一个能交付的扫码页还要处理三件事：识别区域裁剪、防误读去重、成功反馈。
5.1 只识别画面中央区域，解码耗时明显下降
摄像头画面里条码通常会出现在中央，四周都是背景。全帧送给解码器很浪费，常见做法是切一块中央 ROI 再识别：
const roi = document.createElement('canvas'); roi.width = 640; roi.height = 360; const roiCtx = roi.getContext('2d'); function grabRoi() { const sx = video.videoWidth * 0.2; const sy = video.videoHeight * 0.2; const sw = video.videoWidth * 0.6; const sh = video.videoHeight * 0.6; roiCtx.drawImage(video, sx, sy, sw, sh, 0, 0, roi.width, roi.height); return roi; }调用时detector.detect(grabRoi())即可。注意画框时要换算坐标：原图 x = sx + box.x / roi.width * sw，否则识别框画偏。裁剪比例不是越小越好，一旦条码被裁掉一半，解码率会崩。
5.2 连续三帧命中再上报，配合相同值去重
单帧识别结果直接提交的话，一个条码在画面里停留两秒可能上报十几次，还可能偶发单帧误读。加一个简单状态机：同一个值连续命中三帧才 commit，commit 后两秒内相同值不进业务：
let hits = 0; let lastValue = ''; let lastSeenAt = 0; const REQUIRED = 3; const DEBOUNCE_MS = 2000; function onDecoded(value) { const now = Date.now(); if (value !== lastValue || now - lastSeenAt > DEBOUNCE_MS) { hits = 0; lastValue = value; } lastSeenAt = now; hits += 1; if (hits >= REQUIRED) { hits = 0; commit(value); } }commit 里再做业务归属判断，用value.startsWith('EAN13')或者rawValue.includes('SN-')这类前缀过滤，把不属于当前业务的码直接丢掉。web 端扫码的防呆逻辑和硬件扫码枪是同一套思路：可信结果来自"连续多帧一致"，而不是单帧解码成功。
最后的调优点放在反馈上：commit 时用 Web Audio 的 OscillatorNode 放一个 880Hz 短音提示扫码成功，比任何视觉动画都直观。整个流程里如果出现"条码明明在画面里却一直不出结果"，按优先级排查：最窄条像素不足（离远一点让条码占满取景框）、镜头没对上焦、光线频闪干扰，三个里面九成是第一个。
本文还有配套的精品资源，点击获取
