html5-qrcode默认帧率2fps为兼容低端设备,调高需兼顾解码耗时与扫描区域:单帧≤50ms可设fps:15,但必须配合qrbox缩小识别区;移动端推荐fps:10+usebarcodedetectorifsupported:true组合,并用try/catch安全降级zxing.js,同时禁用扫码容器的css动画与滤镜以避免主线程阻塞。

html5-qrcode 默认帧率太低,怎么调高又不卡顿
默认 fps 设为 2 是为了兼容低端设备,但多数现代手机和桌面摄像头完全能跑 10–15 FPS。盲目调高会触发主线程阻塞,反而让 UI 冻结或扫码失败。
- 先用
performance.now()测单帧解码耗时:如果稳定在50ms以内,fps: 15是安全的 - 设置
fps同时必须配qrbox缩小扫描区域,否则全帧处理会让高帧率变成负优化 - 避免在
Html5Qrcode实例创建后动态改fps,它不支持运行时热更新,需销毁重建 - 移动端建议用
fps: 10+useBarCodeDetectorIfSupported: true组合,比强行拉到 15 更稳
BarcodeDetector 引擎报错 “Not supported” 怎么 fallback
BarcodeDetector 在 Safari 14.1+、Chrome 83+ 才可用,但部分安卓 WebView 或旧版微信内置浏览器会返回 undefined 或抛出 SecurityError,不能只靠 'BarcodeDetector' in window 判断。
- 要用
try/catch实际初始化一次:try { new BarcodeDetector(); useNative = true; } catch (e) { useNative = false; } - fallback 到
ZXing.js时,记得关掉verbose: true,否则每帧都打日志,CPU 占用飙升 - 某些企业微信环境即使支持
BarcodeDetector,也会因权限策略拒绝访问,此时需加 UA 检测:navigator.userAgent.includes('wxwork')
扫描框抖动、识别延迟高,是不是 CSS 动画惹的祸
很多团队给扫码容器加了 opacity 过渡、transform 动画或伪元素描边,这些都会强制浏览器每帧重绘,挤占解码线程资源。
- 扫码区域的 DOM 必须是
will-change: auto(即不设 will-change),设成transform反而触发多余合成层 - 所有
@keyframes动画在扫码启动时应暂停:document.querySelector('.qrcode-overlay').style.animationPlayState = 'paused' - 用
border替代box-shadow做扫描框边框,后者触发更重的渲染流水线 - 检查是否用了
filter: blur()或backdrop-filter,这些在部分安卓机型上直接禁用硬件加速
构建产物里 html5-qrcode 体积太大,怎么瘦身
完整版 html5-qrcode.min.js 超过 1.2MB,主要是内嵌了 ZXing.js 全量解码逻辑。实际项目中 90% 场景根本用不到 PDF417 或 DataMatrix 支持。
- 用官方提供的按需构建脚本:
npx html5-qrcode-build --exclude=pdf417,data-matrix,可砍掉 400KB+ - Webpack 用户可在
resolve.alias中指向精简后的 dist 文件,避免误引全量包 - 如果只用
BarcodeDetector,干脆删掉zxing-js相关 chunk,再通过externals排除它 - 注意:删减后
Html5QrcodeScanner类不可用,得改用底层Html5QrcodeAPI 手动控制生命周期
offsetWidth 读取,都可能让首帧延迟翻倍。这点连不少性能监控工具都漏报。前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











