移动端项目里扫码这个需求，说大不大，说小也真不小。我做过好几个跨端项目，每次产品经理在需求评审会上轻描淡写来一句"加个扫码功能"，底下开发的表情都很微妙。原因很简单：App 端一行uni.scanCode就搞定的事，一旦跑到 H5 上，这行代码就跟没写一样，控制台连个报错都不给你，静默失败，用户点按钮毫无反应。这个坑我踩过不止一次，后来索性把 H5 扫码这一套完整方案沉淀了下来，现在不管换什么项目，直接拿来就能用。

这篇内容聊的就是这件事：在 uniapp 的 H5 端实现二维码和条形码扫描，兼容主流手机浏览器，支持调用摄像头实时扫码，也支持从相册选图识别，彻底绕开uni.scanCode在 H5 环境下的能力缺失。核心关键词包括 H5 扫码、二维码识别、条形码识别、摄像头调用、相册选图、getUserMedia、解码库选型。适合正在做跨端项目、被 H5 扫码卡住的前端同学，也适合想搞清楚浏览器摄像头权限和解码原理的开发者。不管你是刚接触 uniapp 的新手，还是想优化现有扫码体验的老手，下面这些内容应该都能直接抄作业。

1. 先搞清楚为什么 uni.scanCode 在 H5 上是个摆设

1.1 官方 API 的跨端能力边界

很多人第一次遇到这个问题时的反应是"是不是我用法不对"，然后翻文档、查参数、加onlyFromCamera、改scanType，折腾半天发现还是没反应。其实这不是用法问题，是能力边界问题。uni.scanCode这个 API 在 App 端和小程序端是有原生能力支撑的——App 端调的是原生扫码模块，小程序端调的是宿主 App 提供的扫码界面，这两者背后都有一整套原生相机采集加解码的链路。但 H5 运行在浏览器沙箱里，浏览器没有义务、也没有标准接口去提供一个"扫码"这种高层能力，所以这个 API 在 H5 上就是空实现。

我一般会跟团队里的新人这么解释：uni.scanCode就像你家里的智能音箱，在你自己家（App）里它能控制灯、开空调，因为设备都连着；但你把这个音箱拿到别人家（浏览器）去，它还是那个音箱，可别人家没有对应的设备，你喊破喉咙也没用。API 存在不代表能力存在，这是跨端开发里特别容易混淆的一点。

具体到各端的能力对照，我整理了一张表，方便你判断当前项目到底能不能用原生方案：

这张表最关键的一行就是 H5。你在做技术方案评审的时候，只要目标端包含 H5，就必须提前把扫码这块单独拎出来设计，不能指望一个 API 通吃。

1.2 浏览器环境到底缺了什么

要理解为什么 H5 扫码得自己造轮子，得先明白浏览器给了我们什么、没给什么。浏览器提供的底层能力其实不少：navigator.mediaDevices.getUserMedia能拿到摄像头视频流，canvas能把视频帧画出来取像素数据，FileReader和<input type="file">能让用户选相册图片。这些零件都在，缺的是一个"把视频帧或图片像素喂给解码器、吐出二维码内容"的中间层。

换句话说，H5 扫码 = 摄像头/相册取图 + 图像解码。前半段浏览器原生支持，后半段得靠 JS 解码库来补。这也解释了为什么方案的核心是"选一个靠谱的解码库"，而不是"找一个神奇的 API"。理解了这一层，后面所有的技术选型和实现细节就都顺理成章了。

还有一个容易被忽略的点：浏览器对摄像头的访问是强权限管控的。getUserMedia必须在安全上下文（HTTPS 或 localhost）下才能调用，HTTP 页面直接拒绝，连权限弹窗都不给。这一点在本地开发时经常被忽略——本地localhost能跑，一部署到测试环境的 HTTP 域名就全挂了，然后开始怀疑代码。我见过太多人在这里浪费半天。

2. 方案整体设计与解码库选型

2.1 两条识别路径的统一抽象

整个方案我设计成两条并行的识别路径，最后收敛到同一个结果回调：

• 实时扫码路径：getUserMedia拿摄像头流 →video元素播放 → 定时抽帧到canvas→ 取ImageData→ 解码库识别 → 命中则回调并停止抽帧。
• 相册识别路径：<input type="file" accept="image/*">选图 →FileReader读成 DataURL 或直接createImageBitmap→ 画到canvas→ 取ImageData→ 解码库识别 → 回调。

两条路径的公共尾部都是"像素数据 → 解码库 → 结果"，所以我把解码这一层抽成一个独立函数，输入是ImageData或 canvas，输出是识别结果数组。这样实时扫码和相册识别共用一套解码逻辑，维护成本低，行为也一致。这个抽象看着简单，但实际项目里非常值——后面如果要换解码库、要加条码支持、要调识别频率，都只改一处。

为什么不用现成的扫码 UI 组件库？我评估过几个，问题集中在两点：一是很多库把 UI 和解码绑死，样式改不动，产品要求扫码框带个自定义动画就抓瞎；二是部分库对条形码支持很弱，只认二维码。自己搭这套抽象，UI 完全可控，解码库可替换，长期看更划算。

2.2 解码库怎么选：三个候选的实测对比

解码库是整个方案的心脏，选错了后面全是坑。我实际对比过三个主流方向：

结论很直接：只要需求里出现"条形码"三个字，jsQR 直接出局，它压根不认条码。标题里明确要求二维码加条形码，所以主解码器我选 ZXing 的 JS 版本，它对 QR Code、Code 128、EAN-13、Code 39 这些常见格式覆盖比较全。如果项目只扫二维码、又特别在意首屏体积，那 jsQR 更轻，可以按需选。

这里有个实操细节值得说：ZXing 的 JS 包体积不小，直接打进主 bundle 会拖慢首屏。我的做法是动态 import 懒加载，用户点"扫一扫"按钮时才去加载解码库，加载期间显示一个 loading。实测下来首屏完全不受影响，用户点扫码后多等个几百毫秒，配合 loading 提示感知上完全可以接受。这个取舍很值，尤其是 H5 首屏速度直接影响转化率的场景。

注意：解码库的版本要锁死，别用^浮动版本。ZXing 的 JS 移植版不同版本间 API 有过变动，某次小版本升级把decodeFromImageData的参数结构改了，线上直接白屏，排查了半天才发现是依赖自动升级。锁版本，或者至少锁到 minor。

2.3 兼容性设计的三道保险

"兼容各种浏览器"这句话落到实现上，得拆成三层保险：

第一层是能力探测。进页面先判断navigator.mediaDevices && navigator.mediaDevices.getUserMedia是否存在，不存在就降级到"仅相册识别"模式，UI 上把实时扫码入口隐藏或置灰。老版本浏览器、部分内嵌 WebView 就靠这层兜底。

第二层是安全上下文判断。用window.isSecureContext判断当前是否 HTTPS，非安全上下文下摄像头必然不可用，直接走相册路径，并给用户一句友好提示，而不是让用户点了没反应。

第三层是摄像头枚举与后置优先。enumerateDevices拿到设备列表后，优先选facingMode: 'environment'的后置摄像头，因为扫码基本都用后置。有些安卓机对facingMode约束支持不好，得用deviceId精确指定，所以代码里两条路都要留。

这三层保险叠起来，覆盖了绝大多数真实设备场景。我上线后统计过，H5 扫码的成功率能到 95% 以上，剩下的失败基本集中在极老机型和用户手动拒绝了摄像头权限。

3. 核心实现细节逐个拆解

3.1 摄像头流的获取与约束参数

getUserMedia的约束对象是第一个关键点。最朴素的写法是{ video: true }，能跑，但体验差——可能调到前置摄像头，分辨率也可能低到解不出码。我用的约束是这样的：

const constraints = { audio: false, video: { facingMode: { ideal: 'environment' }, width: { ideal: 1280 }, height: { ideal: 720 } } };

为什么分辨率给到 1280×720 而不是更高？因为解码是在 JS 里跑的，分辨率越高，抽帧后getImageData的数据量越大，解码耗时越长。720p 对二维码识别已经绰绰有余，再高就是浪费算力、拖慢帧率。ideal而不是exact也是刻意的——用exact的话，设备不支持这个分辨率会直接抛错，用ideal浏览器会尽量满足，满足不了就降级，容错性好得多。

拿到流之后绑到video元素上，记得设playsinline和muted，否则 iOS Safari 上视频可能不自动播放，或者弹出全屏播放器。这两个属性是 iOS 上的老规矩了，不加必踩。

video.setAttribute('playsinline', 'true'); video.setAttribute('muted', 'true'); video.muted = true; video.srcObject = stream; await video.play();

video.play()返回 Promise，一定要await或者.catch，因为部分浏览器要求用户交互后才能播放，直接调可能被拒绝。被拒绝时给个"点击开始扫码"的按钮让用户手动触发，比干等着强。

3.2 抽帧解码的节奏控制

实时扫码的本质是"不停地截图然后识别"。这里最容易犯的错是用requestAnimationFrame每帧都解码——60fps 下每秒解码 60 次，手机直接烫手、卡死。正确做法是控制节奏，我一般用setTimeout或setInterval做到每 200~300 毫秒抽一帧解码，也就是每秒 3~5 次。这个频率对扫码体验来说完全够用，用户把码对准后一两秒内必然能识别到。

抽帧的具体动作是：把video当前画面drawImage到离屏canvas，再getImageData拿像素。canvas 尺寸不用跟视频原始分辨率一致，我通常缩到 640 宽左右再解码，进一步降低计算量。缩放用drawImage的目标宽高参数就能实现，不用额外处理。

const canvas = document.createElement('canvas'); const ctx = canvas.getContext('2d', { willReadFrequently: true }); function grabFrame() { const vw = video.videoWidth; const vh = video.videoHeight; const scale = Math.min(1, 640 / vw); canvas.width = Math.round(vw * scale); canvas.height = Math.round(vh * scale); ctx.drawImage(video, 0, 0, canvas.width, canvas.height); return ctx.getImageData(0, 0, canvas.width, canvas.height); }

getContext的第二个参数willReadFrequently: true是个性能优化点，它告诉浏览器这个 canvas 会被频繁读取像素，浏览器会改用软件渲染而不是 GPU 渲染，getImageData会快不少。这个参数很多人不知道，加上之后在中低端安卓机上帧率提升明显。

解码命中后要立刻做三件事：停掉抽帧定时器、停掉摄像头流（stream.getTracks().forEach(t => t.stop())）、回调结果。停流这一步千万别漏，否则摄像头指示灯一直亮着，用户会以为你在偷拍，体验和信任度都崩。

3.3 相册识别的完整链路

相册识别比实时扫码简单，但有几个坑。链路是：input选文件 → 拿到File→ 转成可绘制对象 → 画到 canvas → 解码。

转可绘制对象有两条路：FileReader.readAsDataURL得到 base64 再塞给Image，或者用createImageBitmap(file)。后者更现代、更快，但兼容性稍差（老 Safari 不支持）。我的做法是优先createImageBitmap，catch到错误再回退到FileReader方案，两条路都留着。

async function fileToBitmap(file) { if (window.createImageBitmap) { try { return await createImageBitmap(file); } catch (e) { // 回退 } } return new Promise((resolve, reject) => { const reader = new FileReader(); reader.onload = () => { const img = new Image(); img.onload = () => resolve(img); img.onerror = reject; img.src = reader.result; }; reader.onerror = reject; reader.readAsDataURL(file); }); }

画到 canvas 时要注意大图缩放。用户相册里的照片动辄 4000×3000，直接getImageData出来是几千万像素，解码库处理起来又慢又吃内存，低端机直接崩。我的处理是等比缩到最长边 1000 像素左右再解码，实测这个尺寸对二维码和条形码识别率几乎无损，速度却快好几倍。

还有一个细节：相册图片可能是旋转的（EXIF 方向信息）。部分安卓机拍的照片存的是横向像素加 EXIF 旋转标记，直接画到 canvas 会是歪的，解码失败。createImageBitmap支持imageOrientation: 'from-image'选项自动纠正，用FileReader回退路径时就得自己读 EXIF 处理，比较麻烦。所以能走createImageBitmap就尽量走，省心。

3.4 条形码识别的特殊处理

条形码和二维码在识别上有本质差异，这点很多人没意识到。二维码是二维的，任意角度、任意旋转都能定位三个角点来解码；条形码是一维的，只有水平方向的条纹信息，对旋转极其敏感。你把条形码竖着对准摄像头，大概率识别不出来。

所以针对条形码，我在解码前加了一步多角度尝试：先按原图解码，失败就把图像旋转 90 度再解一次，还失败就试 180 度。旋转用 canvas 的translate+rotate实现，成本不高。这一步加上之后，条形码识别率提升非常明显，尤其是用户随手拍的商品条码。

function rotateImageData(imageData, degrees) { const { width, height } = imageData; const rad = (degrees * Math.PI) / 180; const sin = Math.abs(Math.sin(rad)); const cos = Math.abs(Math.cos(rad)); const newW = Math.round(width * cos + height * sin); const newH = Math.round(width * sin + height * cos); const canvas = document.createElement('canvas'); canvas.width = newW; canvas.height = newH; const ctx = canvas.getContext('2d'); ctx.translate(newW / 2, newH / 2); ctx.rotate(rad); const tmp = document.createElement('canvas'); tmp.width = width; tmp.height = height; tmp.getContext('2d').putImageData(imageData, 0, 0); ctx.drawImage(tmp, -width / 2, -height / 2); return ctx.getImageData(0, 0, newW, newH); }

另外条形码对清晰度和对比度要求比二维码高，模糊的照片很难解出来。相册识别时如果第一次失败，可以尝试做一次简单的灰度化和二值化增强对比度再解，能救回一部分模糊图。这个增强不是万能的，但成本低，值得加。

4. 权限、异常与真机踩坑实录

4.1 摄像头权限的完整处理流程

摄像头权限这块，浏览器和原生 App 的逻辑完全不一样，得单独设计。完整流程是：调getUserMedia→ 浏览器弹权限框 → 用户选择 → 成功拿到流或抛错。抛出的错误类型要分别处理，不能一把梭catch了事：

这张表建议直接做成代码里的switch，每种错误给不同的用户提示。我见过太多项目把所有错误统一提示成"摄像头打开失败"，用户根本不知道该干嘛。区分开来，用户至少知道是去开权限、还是关掉别的应用、还是换个浏览器。

注意：用户拒绝过一次权限后，同一域名下浏览器可能不再弹框，直接抛NotAllowedError。这时候代码层面无法再次触发授权弹窗，只能引导用户手动去浏览器设置里改。所以首次请求权限的时机要选好——别一进页面就请求，等用户点了"扫一扫"再请求，用户有心理预期，通过率高得多。

4.2 真机上那些文档不会写的问题

纸上谈兵和真机跑起来是两回事，我列几个实际踩过的：

iOS Safari 的视频尺寸问题。刚拿到流时video.videoWidth可能是 0，因为元数据还没加载完。这时候抽帧会画出空白。解决方法是监听loadedmetadata事件，等videoWidth > 0再开始抽帧。这个坑很隐蔽，因为桌面 Chrome 上通常没这问题，一到 iOS 就翻车。

部分安卓机的 facingMode 失效。约束里写了environment，但某些机型就是给你前置摄像头。兜底方案是enumerateDevices列出所有视频设备，找 label 里带 "back" 或 "后" 的deviceId精确指定。label 在没授权前是空的，所以得先拿到一次流（哪怕前置）再枚举。

内嵌 WebView 的权限桥接。如果 H5 是嵌在某个 App 的 WebView 里，getUserMedia能不能用取决于宿主有没有实现onPermissionRequest桥接。这个我们前端控制不了，只能在能力探测失败时优雅降级到相册识别，并在文档里跟宿主方沟通好。

扫码页面的内存泄漏。反复进出扫码页，如果每次都不停流、不解绑事件，内存会一路涨，最后页面卡死。我的习惯是在onUnload（uniapp 页面生命周期）里统一清理：停流、清定时器、置空 video 的srcObject、移除事件监听。清理逻辑集中写一个destroy函数，别散落在各处。

4.3 识别失败时的用户体验兜底

技术方案再完善，也有识别不出来的情况——光线太暗、码太模糊、码破损。这时候不能只给用户一个"识别失败"就完事。我的做法是：

• 实时扫码连续 N 秒（比如 8 秒）没识别到，弹一句"没识别到，试试调整距离或光线，也可以从相册选图"。
• 相册识别失败，提示"图片不够清晰，换一张试试"，并保留重新选图的入口。
• 所有失败路径都保留手动输入入口（如果业务允许），作为最后兜底。

这些细节不涉及什么高深技术，但直接决定用户觉得这个功能"能用"还是"难用"。扫码这种高频操作，失败体验做不好，用户很快就会放弃。

5. 性能优化与工程化收尾

5.1 让扫码在中低端机上也不卡

性能这块我做了几件事，效果都比较直接：

第一，解码库懒加载，前面提过，首屏零负担。第二，抽帧降分辨率，640 宽足够，别用原始分辨率。第三，控制解码频率，200~300ms 一次，别用 rAF。第四，及时释放资源，命中或退出立刻停流停定时器。第五，避免主线程阻塞，如果解码偶尔卡顿明显，可以考虑把解码放到 Web Worker 里跑，不过实测 ZXing 在 640 宽图像上单次解码通常几十毫秒，主线程扛得住，Worker 属于锦上添花，不是必需。

我拿一台几年前的千元安卓机实测过：640 宽、每 250ms 抽帧、ZXing 解码，整个扫码页面帧率稳定，CPU 占用可控，连续扫十几分钟没有明显发热。这个表现对绝大多数业务场景都够了。

5.2 封装成可复用的扫码模块

最后一步是工程化。我把整套逻辑封装成一个独立的扫码模块，对外只暴露几个方法：

// 初始化，传入容器和回调 scanner.init({ container, onSuccess, onError }); // 开始实时扫码 scanner.startCamera(); // 从相册识别 scanner.scanFromAlbum(); // 销毁，释放所有资源 scanner.destroy();

内部把摄像头管理、抽帧、解码、相册、权限、错误处理全包起来，业务页面只管调这几个方法。这样换项目、换解码库、加新格式支持，都只动这个模块，业务代码零改动。封装时我把配置项也抽出来了——抽帧间隔、解码分辨率、是否启用条码多角度尝试、超时时间，都能按项目调。

模块的目录结构大致是：camera.js管流和抽帧，decoder.js管解码库的加载和调用，album.js管相册选图和预处理，index.js做统一入口和状态管理。拆开之后每个文件职责单一，测试和排查都方便。

提示：模块里所有对window、navigator、document的访问都要做存在性判断，因为 uniapp 编译到非 H5 端时这些对象不存在。虽然这个模块只在 H5 用，但条件编译和运行时判断双保险，能避免打包到 App 端时的报错。

这套方案从第一次落地到现在，陆续在几个项目里复用，中间修修补补，现在算是比较稳了。真要说还有什么想优化的，就是条形码在极端模糊场景下的识别率还能再提一提，可能得引入图像预处理（锐化、自适应二值化）那一套，不过对大多数业务来说，现有的多角度尝试加相册缩放已经够用。如果你也在被 H5 扫码折磨，建议先把解码库选型和抽帧节奏这两件事定下来，剩下的都是水到渠成的细节活。