起攝像頭識別條形碼實戰(zhàn)：getUserMedia+jsQR完整指南)
簡介手機攝像頭實時識別條形碼的H5實踐資源面向Web前端與移動端開發(fā)者演示不依賴原生App、在瀏覽器環(huán)境中完成掃碼的實現(xiàn)思路適用于電商、物流、庫存管理等場景對希望低成本接入掃碼能力的前端用戶尤其友好。壓縮包共3個文件包括1個HTML示例頁與2個JavaScript腳本——jquery庫提供基礎DOM操作Quagga掃碼庫負責視頻流解析與條碼識別總大小僅291KB輕量易用下載后可直接打開頁面體驗。目前已有1681人學習/下載。示例圍繞HTML5的video標簽、getUserMedia API和QuaggaJS展開包含攝像頭視頻流獲取、掃碼區(qū)域配置、Code 128條碼解碼及onDetected回調(diào)處理等關鍵代碼較為完整地呈現(xiàn)了實時掃碼流程讀者可據(jù)此快速搭建可運行Demo并進一步擴展其他條碼類型、適配移動端UI或將識別結果通過后臺接口實時同步滿足庫存盤點、快遞掃碼等業(yè)務需要。 前段時間接了個需求在 H5 頁面里調(diào)起手機攝像頭識別條形碼。聽起來不算復雜但真做起來才發(fā)現(xiàn)坑不少——權限、兼容性、識別率、性能每一環(huán)都可能翻車。這篇就完整拆一遍從技術選型到核心實現(xiàn)到避坑給后來人一個可以直接參考的方案。這個需求的實際場景很典型倉庫盤點、門店核銷、自助機頁面、醫(yī)療耗材掃碼等。網(wǎng)頁端要掃條形碼以前只能靠第三方 App 或者原生殼現(xiàn)在用 HTML5 的能力就能實現(xiàn)。核心鏈路其實就一句話調(diào)起攝像頭獲取視頻流截幀后交給解碼庫識別條形碼內(nèi)容。1. 項目概述與需求拆解1.1 這個需求背后的真實場景在動手寫代碼之前先把需求想明白。表面上是“識別條形碼”但業(yè)務上往往有更多隱含要求識別速度用戶把手機對準條碼如果 2 秒內(nèi)不出結果體驗就會直線下降。識別類型是 EAN-13、Code128、Code39還是 QR 碼條形碼和二維碼的解碼庫側重點不同。連續(xù)識別是掃一次就停還是需要連續(xù)掃碼比如批量盤點場景用戶會連續(xù)掃多個條碼。使用環(huán)境是普通瀏覽器、微信內(nèi)置瀏覽器、企業(yè)微信還是被 App 的 WebView 嵌套不同容器的權限策略差別很大。這些沒搞清楚就開寫后面大概率返工。所以我一般先把“識別什么碼、在什么環(huán)境用、掃完干什么”這三件事問清楚再進入技術方案。1.2 技術選型幾條路線的對比H5 識別條形碼業(yè)界主流方案有這么幾種方案實現(xiàn)思路優(yōu)點缺點原生getUserMedia jsQR自己調(diào)攝像頭截幀后用 jsQR 解碼輕量、可控性強、無額外請求需要自己處理權限和兼容性代碼量偏大封裝庫html5-qrcode內(nèi)部封裝了攝像頭調(diào)用和識別邏輯API 簡單、上手快、支持掃碼槍模擬定制性稍弱移動端性能一般ZXing 的 JS 移植版Java 庫轉成 JS支持的碼制更全庫體積較大維護活躍度一般商業(yè)庫如 Dynamsoft成熟商用方案識別率和碼制覆蓋最穩(wěn)商用收費個人小項目不建議我的選擇是原生拖幀 jsQR。原因很簡單條形碼識別這個場景jsQR 對 Code128、EAN-13、EAN-8 這些常見碼制支持得很好而且純前端解析視頻幀不經(jīng)過服務器也沒有額外的網(wǎng)絡延遲。相比用html5-qrcode這種封裝庫原生方案在幀率控制、識別區(qū)域裁剪上更靈活排查問題也更直接。注意jsQR 對 QR 碼的支持也很好但如果你只需要識別一維條形碼并且對識別率要求極高可以考慮把jsQR換成BarcodeDetector瀏覽器原生 API不過它的兼容性目前還一般后面會詳說。2. 環(huán)境準備與前置條件2.1 HTTPS 和瀏覽器權限在本地localhost上調(diào)試時getUserMedia是允許的一旦上線所有頁面必須走 HTTPS否則瀏覽器會直接拒絕攝像頭權限。很多新手在這里踩了第一坑本地好好的部署到測試服就黑屏。微信、支付寶這些內(nèi)置瀏覽器以及 App 的 WebView對權限的處理也各有差異。以微信為例iOS 端的 WebView 在請求攝像頭權限時會彈系統(tǒng)授權框Android 端部分舊版本 X5 內(nèi)核則可能需要單獨配置權限申請。所以在項目啟動初期就要把“能用 HTTPS、能彈授權框”這兩個前提先驗證掉別等代碼寫完才發(fā)現(xiàn)環(huán)境不支持?？梢杂孟旅孢@段代碼快速驗證當前環(huán)境是否支持攝像頭調(diào)用if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) { alert(當前瀏覽器不支持攝像頭調(diào)用); }2.2 攝像頭畫面的獲取流程H5 拿攝像頭畫面靠的是navigator.mediaDevices.getUserMedia它返回一個MediaStream里面包含視頻軌道。拿到視頻流之后把它塞給video標簽就能實時預覽。但從“看到畫面”到“識別條形碼”中間還有一步很關鍵視頻流不能直接傳給解碼器必須先截一幀到canvas再把canvas的圖像數(shù)據(jù)交給 jsQR 解析。這相當于給解碼器喂一張靜態(tài)圖片。有一個容易被忽略的點在手機瀏覽器里前置攝像頭的視頻流默認是鏡像的后置攝像頭一般正常。掃描條形碼場景我們需要后置攝像頭通過facingMode: environment來指定const constraints { video: { facingMode: { exact: environment } // 強制后置攝像頭 } };這里我用的是exact表示嚴格匹配后置。如果某些設備拿不到后置請求會失敗如果改成facingMode: environment不帶 exact瀏覽器會盡量匹配實在沒有就用默認攝像頭。實際項目中建議先用不帶 exact 的寫法做降級保證兼容性。3. 核心實現(xiàn)三步完成條形碼識別3.1 調(diào)起攝像頭并顯示預覽先寫一個最基礎的 HTML 結構video idvideo autoplay playsinline muted/video canvas idcanvas styledisplay:none/canvas這里playsinline很重要iOS Safari 默認會嘗試全屏播放視頻加上這個屬性才能保持內(nèi)聯(lián)預覽。muted也是 iOS 的要求之一靜音視頻播放才不會被瀏覽器攔截。然后調(diào)起攝像頭async function initCamera() { try { const stream await navigator.mediaDevices.getUserMedia({ video: { facingMode: environment }, audio: false }); const video document.getElementById(video); video.srcObject stream; await video.play(); // 等 video 真正開始播放后再啟動識別循環(huán) startScanLoop(); } catch (err) { console.error(攝像頭調(diào)用失敗:, err); } }有個細節(jié)video.play()返回的是 Promise在部分安卓瀏覽器上不 await 直接進入識別循環(huán)videoWidth可能還是 0導致 canvas 畫出來是黑圖。所以代碼里我強烈建議await video.play()。3.2 截幀與解碼接下來是識別循環(huán)。核心思路是定時從 video 上抓一幀塞給 jsQR 解析。function startScanLoop() { const video document.getElementById(video); const canvas document.getElementById(canvas); const ctx canvas.getContext(2d, { willReadFrequently: true }); // 注意willReadFrequently 可以提升 getImageData 的性能 setInterval(() { if (video.readyState video.HAVE_ENOUGH_DATA) { // 縮小 canvas減少計算量 const targetWidth 480; const scale Math.min(1, targetWidth / video.videoWidth); canvas.width video.videoWidth * scale; canvas.height video.videoHeight * scale; ctx.drawImage(video, 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); if (code code.data) { handleScanResult(code.data); } } }, 100); // 每 100ms 識別一幀 }這段代碼里有幾個優(yōu)化點值得說細一點。第一canvas 的寬高沒必要跟視頻原始分辨率一樣。手機上視頻流分辨率動輒 1920×1080如果直接拿這個尺寸去解碼每一幀的計算量非常大手機會發(fā)熱識別率反而不穩(wěn)定。實踐中我習慣把最長邊縮到 480px 左右。這個值足夠 jsQR 識別條形碼同時把計算量降低好幾個量級。第二getImageData的性能優(yōu)化。Canvas 的getContext(2d)默認是為了繪制設計的對頻繁讀取像素數(shù)據(jù)沒有做特殊優(yōu)化。在創(chuàng)建 context 時傳入{ willReadFrequently: true }能讓瀏覽器知道你要反復讀像素從而選擇更適合的內(nèi)存布局。這個參數(shù)很實用算是一個小技巧。第三識別頻率不必太高。每秒 10 幀100ms 一次已經(jīng)足夠。掃碼的本質是用戶把條碼對準攝像頭畫面穩(wěn)定后識別成功往往就在一兩幀內(nèi)幀率再高不僅耗電還會讓 CPU 持續(xù)滿載。3.3 識別結果的去重與回調(diào)實際使用中還會遇到另一個問題連續(xù)識別時同一個條碼會被反復掃到。比如用戶掃一次貨架上的條碼jsQR 在畫面穩(wěn)定的那 200ms 里解碼成功了 3 次如果每次回調(diào)都觸發(fā)業(yè)務邏輯就會重復提交。所以要加一個簡單的“防抖”邏輯let lastResult ; let lastResultTime 0; const DEBOUNCE_MS 2000; // 2 秒內(nèi)同一個碼只觸發(fā)一次 function handleScanResult(data) { const now Date.now(); if (data lastResult now - lastResultTime DEBOUNCE_MS) { return; } lastResult data; lastResultTime now; // 這里再跳轉到你的業(yè)務處理邏輯 console.log(識別到條碼:, data); }這個邏輯很樸素但很管用。設置 2 秒的去重時間既不會讓用戶覺得“掃一次彈好幾下”又能在用戶連續(xù)掃兩個相同條碼時正常觸發(fā)第二次。3.4 關閉攝像頭一個容易被忽視的收尾很多人在掃碼成功后直接跳轉頁面根本不管攝像頭有沒有關。H 5 頁面如果不主動停掉視頻流攝像頭指示燈會一直亮著用戶會非常不安。正確的做法是function stopCamera() { const video document.getElementById(video); if (video video.srcObject) { video.srcObject.getTracks().forEach(track track.stop()); video.srcObject null; } }注意要調(diào)用getTracks().forEach(track track.stop())把上面的所有軌道都停掉而不僅僅是停 video 標簽。這個操作在掃碼成功跳轉前、頁面卸載前都要做一遍。4. 常見問題與排查技巧實錄4.1 攝像頭打不開權限與環(huán)境的排查路徑攝像頭打不開是遇到最多的問題原因通常有以下幾類現(xiàn)象可能原因排查方向返回NotAllowedError用戶拒絕了授權檢查是否有引導用戶開啟權限的邏輯返回NotFoundError設備沒有攝像頭或 constraint 不滿足改用不帶 exact 的 facingMode直接黑屏無反應HTTPS 未配置或瀏覽器版本不支持檢查頁面協(xié)議、內(nèi)核版本在微信里打不開微信內(nèi)置瀏覽器權限策略限制測試原生瀏覽器排除問題必要時引導用系統(tǒng)瀏覽器打開有一個特別容易踩的坑getUserMedia在用戶點擊事件之外調(diào)用某些瀏覽器會直接拒絕授權彈窗。比如頁面加載后就自動調(diào)攝像頭Safari 可能不給彈權限框。解決辦法是把初始化攝像頭綁在“開始掃碼”按鈕的點擊事件里。4.2 識別率低畫面清晰度與光照的影響jsQR 的解碼效果高度依賴輸入圖像質量。最常見的識別失敗原因不是算法不行而是條碼在畫面里太小、太暗或者反光。實際調(diào)優(yōu)時可以參考這幾個方向距離引導頁面加一條輔助線提示用戶把條碼放在畫面中央?yún)^(qū)域。禁止縮放有些瀏覽器會自動對 video 做縮放導致條碼變虛。可以給 video 加object-fit: cover讓畫面鋪滿容器。裁剪識別區(qū)域優(yōu)先掃描畫面中央的條碼還可以預處理圖像比如去噪、增強對比度或做灰度化處理。jsQR 內(nèi)部會做灰度化但如果你在裁剪區(qū)域做了額外預處理比如用ctx.filter contrast(1.2)增強對比度在暗光環(huán)境下往往有意外驚喜。提示光線如果環(huán)境光不足建議在頁面上給出“光線不足”的提示。這個可以用視頻幀的平均亮度來判斷但不是必須根據(jù)自己的場景決定。4.3 瀏覽器原生掃碼 APIBarcodeDetector除了 jsQR瀏覽器現(xiàn)在提供了一個原生的BarcodeDetectorAPI可以直接識別條碼還支持指定碼制EAN-13、QR_CODE 等識別速度比純 JS 庫快不少。if (BarcodeDetector in window) { const detector new BarcodeDetector({ formats: [ean_13, code_128, qr_code] }); const barcodes await detector.detect(canvas); // barcodes[0].rawValue 就是識別結果 }但這個 API 目前最大的問題是兼容性參差不齊Chrome 桌面端和 Android 上支持較好iOS Safari 截至最近仍未完整支持微信內(nèi)置瀏覽器就更不一定了。我的建議是把 BarcodeDetector 當成一個漸進增強的能力優(yōu)先用 jsQR 保證全端一致檢測到支持 BarcodeDetector 時再切換過去。4.4 微信小程序和 App 嵌套 H5 的場景注意點看熱搜詞里很多人關心“H5 能不能調(diào)用微信小程序當前經(jīng)緯度”“小程序跳 H5 頁面”這類問題這里順帶說一下。H5 頁面在小程序 WebView 里運行時攝像頭權限策略和小程序原生組件完全是兩套邏輯。小程序的camera組件權限在小程序側H5 的getUserMedia權限在 WebView 側。如果你遇到在小程序里 H5 調(diào)不起攝像頭大概率是 WebView 沒有把攝像頭權限授權給頁面需要在 App 或小程序的 web-view 配置里處理。同樣App 里嵌套 H5 時Android 端的 WebView 需要在原生層申請CAMERA權限并且設置WebChromeClient.onPermissionRequest回調(diào)否則 H5 調(diào)用getUserMedia時會靜默失敗。這些問題前端單獨排查不出來得拉上客戶端開發(fā)一起聯(lián)調(diào)。4.5 頁面報錯排查技巧我把一些常見的報錯信息整理成了一個速查表方便大家快速定位報錯信息含義解決方向TypeError: Cannot read property getUserMedia of undefined瀏覽器不支持檢查 HTTPS、瀏覽器版本、內(nèi)核OverconstrainedError指定的 facingMode 無法滿足去掉exact限定NotReadableError攝像頭被其他程序占用關閉其他用到攝像頭的頁面或 AppAbortError用戶主動取消授權提示用戶重新授權在 button 點擊回調(diào)中重新調(diào)用 getUserMedia5. 關于性能優(yōu)化和用戶體驗的幾點心得最后分享一些交互層面的經(jīng)驗。別讓用戶自己點“開始”。很多掃碼頁面把攝像頭調(diào)用放在一個“開始掃碼”按鈕上這其實多了一步操作。用戶點進頁面目的就是掃碼直接在頁面加載后自動拉起攝像頭記得通過用戶手勢觸發(fā)比如監(jiān)聽點擊后調(diào)用配合一個半透明遮罩框提示“將條碼置于框內(nèi)”體驗順很多。識別成功要有明確的視覺和聲音反饋。視覺上可以做一個綠色的對勾框閃一下聲音上如果可以調(diào)用系統(tǒng)的震動或悅耳的提示音就更好。用戶掃完條碼如果在 200ms 內(nèi)沒看到任何反饋會下意識反復晃手機反而讓后續(xù)識別更困難。識別區(qū)域別占滿整個屏幕。對齊輔助框通常放在屏幕中部寬度約為屏幕的三分之二。這個區(qū)域內(nèi)識別準確率和速度最高。用戶把條碼對準框內(nèi)比整個屏幕胡亂晃動要穩(wěn)定得多。注意 H5 頁面在頁面切后臺時的處理。用visibilitychange事件在頁面隱藏時停止識別循環(huán)回到前臺時再恢復。否則用戶切到其他 App 再返回頁面還在瘋狂解碼耗電發(fā)熱不說還可能拿到一堆無效圖像。這一塊代碼很簡單但很能體現(xiàn)細節(jié)。6. 整套方案的最終形態(tài)把上面的步驟合在一起一個完整的 H5 掃碼頁面功能就成型了頁面加載后點擊按鈕調(diào)起getUserMedia視頻流實時預覽在video標簽中setInterval定時截幀到canvasjsQR解碼canvas圖像解碼成功后去重、回傳業(yè)務處理跳轉或停止攝像頭釋放視頻流。我后來把這套方案沉淀成了一個公共組件業(yè)務側只需要傳入“識別成功后做什么”的回調(diào)函數(shù)。目前已經(jīng)用在掃碼核銷、設備巡檢幾個項目里整體識別成功率在室內(nèi)光照環(huán)境下能穩(wěn)定在 98% 以上解碼耗時單幀大約 20~40ms用戶體驗是比較流暢的。有一點值得強調(diào)H5 掃碼方案本質上是“用瀏覽器能力模擬掃碼槍”它在便利性上有無可替代的優(yōu)勢但與原生掃碼在弱光、強反光等極端場景下仍有差距。如果你們的業(yè)務對識別率有極致要求比如密集貨架、大幅面的 Code128 標簽建議在前端方案之上再搭配原生掃碼組件兜底。兩者結合才是一個生產(chǎn)級掃碼功能的完整形態(tài)。本文還有配套的精品資源點擊獲取 H5調(diào)起攝像頭識別條形碼實戰(zhàn)：getUserMedia+jsQR完整指南
簡介手機攝像頭實時識別條形碼的H5實踐資源面向Web前端與移動端開發(fā)者演示不依賴原生App、在瀏覽器環(huán)境中完成掃碼的實現(xiàn)思路適用于電商、物流、庫存管理等場景對希望低成本接入掃碼能力的前端用戶尤其友好。壓縮包共3個文件包括1個HTML示例頁與2個JavaScript腳本——jquery庫提供基礎DOM操作Quagga掃碼庫負責視頻流解析與條碼識別總大小僅291KB輕量易用下載后可直接打開頁面體驗。目前已有1681人學習/下載。示例圍繞HTML5的video標簽、getUserMedia API和QuaggaJS展開包含攝像頭視頻流獲取、掃碼區(qū)域配置、Code 128條碼解碼及onDetected回調(diào)處理等關鍵代碼較為完整地呈現(xiàn)了實時掃碼流程讀者可據(jù)此快速搭建可運行Demo并進一步擴展其他條碼類型、適配移動端UI或將識別結果通過后臺接口實時同步滿足庫存盤點、快遞掃碼等業(yè)務需要。 前段時間接了個需求在 H5 頁面里調(diào)起手機攝像頭識別條形碼。聽起來不算復雜但真做起來才發(fā)現(xiàn)坑不少——權限、兼容性、識別率、性能每一環(huán)都可能翻車。這篇就完整拆一遍從技術選型到核心實現(xiàn)到避坑給后來人一個可以直接參考的方案。這個需求的實際場景很典型倉庫盤點、門店核銷、自助機頁面、醫(yī)療耗材掃碼等。網(wǎng)頁端要掃條形碼以前只能靠第三方 App 或者原生殼現(xiàn)在用 HTML5 的能力就能實現(xiàn)。核心鏈路其實就一句話調(diào)起攝像頭獲取視頻流截幀后交給解碼庫識別條形碼內(nèi)容。1. 項目概述與需求拆解1.1 這個需求背后的真實場景在動手寫代碼之前先把需求想明白。表面上是“識別條形碼”但業(yè)務上往往有更多隱含要求識別速度用戶把手機對準條碼如果 2 秒內(nèi)不出結果體驗就會直線下降。識別類型是 EAN-13、Code128、Code39還是 QR 碼條形碼和二維碼的解碼庫側重點不同。連續(xù)識別是掃一次就停還是需要連續(xù)掃碼比如批量盤點場景用戶會連續(xù)掃多個條碼。使用環(huán)境是普通瀏覽器、微信內(nèi)置瀏覽器、企業(yè)微信還是被 App 的 WebView 嵌套不同容器的權限策略差別很大。這些沒搞清楚就開寫后面大概率返工。所以我一般先把“識別什么碼、在什么環(huán)境用、掃完干什么”這三件事問清楚再進入技術方案。1.2 技術選型幾條路線的對比H5 識別條形碼業(yè)界主流方案有這么幾種方案實現(xiàn)思路優(yōu)點缺點原生getUserMedia jsQR自己調(diào)攝像頭截幀后用 jsQR 解碼輕量、可控性強、無額外請求需要自己處理權限和兼容性代碼量偏大封裝庫html5-qrcode內(nèi)部封裝了攝像頭調(diào)用和識別邏輯API 簡單、上手快、支持掃碼槍模擬定制性稍弱移動端性能一般ZXing 的 JS 移植版Java 庫轉成 JS支持的碼制更全庫體積較大維護活躍度一般商業(yè)庫如 Dynamsoft成熟商用方案識別率和碼制覆蓋最穩(wěn)商用收費個人小項目不建議我的選擇是原生拖幀 jsQR。原因很簡單條形碼識別這個場景jsQR 對 Code128、EAN-13、EAN-8 這些常見碼制支持得很好而且純前端解析視頻幀不經(jīng)過服務器也沒有額外的網(wǎng)絡延遲。相比用html5-qrcode這種封裝庫原生方案在幀率控制、識別區(qū)域裁剪上更靈活排查問題也更直接。注意jsQR 對 QR 碼的支持也很好但如果你只需要識別一維條形碼并且對識別率要求極高可以考慮把jsQR換成BarcodeDetector瀏覽器原生 API不過它的兼容性目前還一般后面會詳說。2. 環(huán)境準備與前置條件2.1 HTTPS 和瀏覽器權限在本地localhost上調(diào)試時getUserMedia是允許的一旦上線所有頁面必須走 HTTPS否則瀏覽器會直接拒絕攝像頭權限。很多新手在這里踩了第一坑本地好好的部署到測試服就黑屏。微信、支付寶這些內(nèi)置瀏覽器以及 App 的 WebView對權限的處理也各有差異。以微信為例iOS 端的 WebView 在請求攝像頭權限時會彈系統(tǒng)授權框Android 端部分舊版本 X5 內(nèi)核則可能需要單獨配置權限申請。所以在項目啟動初期就要把“能用 HTTPS、能彈授權框”這兩個前提先驗證掉別等代碼寫完才發(fā)現(xiàn)環(huán)境不支持?？梢杂孟旅孢@段代碼快速驗證當前環(huán)境是否支持攝像頭調(diào)用if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) { alert(當前瀏覽器不支持攝像頭調(diào)用); }2.2 攝像頭畫面的獲取流程H5 拿攝像頭畫面靠的是navigator.mediaDevices.getUserMedia它返回一個MediaStream里面包含視頻軌道。拿到視頻流之后把它塞給video標簽就能實時預覽。但從“看到畫面”到“識別條形碼”中間還有一步很關鍵視頻流不能直接傳給解碼器必須先截一幀到canvas再把canvas的圖像數(shù)據(jù)交給 jsQR 解析。這相當于給解碼器喂一張靜態(tài)圖片。有一個容易被忽略的點在手機瀏覽器里前置攝像頭的視頻流默認是鏡像的后置攝像頭一般正常。掃描條形碼場景我們需要后置攝像頭通過facingMode: environment來指定const constraints { video: { facingMode: { exact: environment } // 強制后置攝像頭 } };這里我用的是exact表示嚴格匹配后置。如果某些設備拿不到后置請求會失敗如果改成facingMode: environment不帶 exact瀏覽器會盡量匹配實在沒有就用默認攝像頭。實際項目中建議先用不帶 exact 的寫法做降級保證兼容性。3. 核心實現(xiàn)三步完成條形碼識別3.1 調(diào)起攝像頭并顯示預覽先寫一個最基礎的 HTML 結構video idvideo autoplay playsinline muted/video canvas idcanvas styledisplay:none/canvas這里playsinline很重要iOS Safari 默認會嘗試全屏播放視頻加上這個屬性才能保持內(nèi)聯(lián)預覽。muted也是 iOS 的要求之一靜音視頻播放才不會被瀏覽器攔截。然后調(diào)起攝像頭async function initCamera() { try { const stream await navigator.mediaDevices.getUserMedia({ video: { facingMode: environment }, audio: false }); const video document.getElementById(video); video.srcObject stream; await video.play(); // 等 video 真正開始播放后再啟動識別循環(huán) startScanLoop(); } catch (err) { console.error(攝像頭調(diào)用失敗:, err); } }有個細節(jié)video.play()返回的是 Promise在部分安卓瀏覽器上不 await 直接進入識別循環(huán)videoWidth可能還是 0導致 canvas 畫出來是黑圖。所以代碼里我強烈建議await video.play()。3.2 截幀與解碼接下來是識別循環(huán)。核心思路是定時從 video 上抓一幀塞給 jsQR 解析。function startScanLoop() { const video document.getElementById(video); const canvas document.getElementById(canvas); const ctx canvas.getContext(2d, { willReadFrequently: true }); // 注意willReadFrequently 可以提升 getImageData 的性能 setInterval(() { if (video.readyState video.HAVE_ENOUGH_DATA) { // 縮小 canvas減少計算量 const targetWidth 480; const scale Math.min(1, targetWidth / video.videoWidth); canvas.width video.videoWidth * scale; canvas.height video.videoHeight * scale; ctx.drawImage(video, 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); if (code code.data) { handleScanResult(code.data); } } }, 100); // 每 100ms 識別一幀 }這段代碼里有幾個優(yōu)化點值得說細一點。第一canvas 的寬高沒必要跟視頻原始分辨率一樣。手機上視頻流分辨率動輒 1920×1080如果直接拿這個尺寸去解碼每一幀的計算量非常大手機會發(fā)熱識別率反而不穩(wěn)定。實踐中我習慣把最長邊縮到 480px 左右。這個值足夠 jsQR 識別條形碼同時把計算量降低好幾個量級。第二getImageData的性能優(yōu)化。Canvas 的getContext(2d)默認是為了繪制設計的對頻繁讀取像素數(shù)據(jù)沒有做特殊優(yōu)化。在創(chuàng)建 context 時傳入{ willReadFrequently: true }能讓瀏覽器知道你要反復讀像素從而選擇更適合的內(nèi)存布局。這個參數(shù)很實用算是一個小技巧。第三識別頻率不必太高。每秒 10 幀100ms 一次已經(jīng)足夠。掃碼的本質是用戶把條碼對準攝像頭畫面穩(wěn)定后識別成功往往就在一兩幀內(nèi)幀率再高不僅耗電還會讓 CPU 持續(xù)滿載。3.3 識別結果的去重與回調(diào)實際使用中還會遇到另一個問題連續(xù)識別時同一個條碼會被反復掃到。比如用戶掃一次貨架上的條碼jsQR 在畫面穩(wěn)定的那 200ms 里解碼成功了 3 次如果每次回調(diào)都觸發(fā)業(yè)務邏輯就會重復提交。所以要加一個簡單的“防抖”邏輯let lastResult ; let lastResultTime 0; const DEBOUNCE_MS 2000; // 2 秒內(nèi)同一個碼只觸發(fā)一次 function handleScanResult(data) { const now Date.now(); if (data lastResult now - lastResultTime DEBOUNCE_MS) { return; } lastResult data; lastResultTime now; // 這里再跳轉到你的業(yè)務處理邏輯 console.log(識別到條碼:, data); }這個邏輯很樸素但很管用。設置 2 秒的去重時間既不會讓用戶覺得“掃一次彈好幾下”又能在用戶連續(xù)掃兩個相同條碼時正常觸發(fā)第二次。3.4 關閉攝像頭一個容易被忽視的收尾很多人在掃碼成功后直接跳轉頁面根本不管攝像頭有沒有關。H 5 頁面如果不主動停掉視頻流攝像頭指示燈會一直亮著用戶會非常不安。正確的做法是function stopCamera() { const video document.getElementById(video); if (video video.srcObject) { video.srcObject.getTracks().forEach(track track.stop()); video.srcObject null; } }注意要調(diào)用getTracks().forEach(track track.stop())把上面的所有軌道都停掉而不僅僅是停 video 標簽。這個操作在掃碼成功跳轉前、頁面卸載前都要做一遍。4. 常見問題與排查技巧實錄4.1 攝像頭打不開權限與環(huán)境的排查路徑攝像頭打不開是遇到最多的問題原因通常有以下幾類現(xiàn)象可能原因排查方向返回NotAllowedError用戶拒絕了授權檢查是否有引導用戶開啟權限的邏輯返回NotFoundError設備沒有攝像頭或 constraint 不滿足改用不帶 exact 的 facingMode直接黑屏無反應HTTPS 未配置或瀏覽器版本不支持檢查頁面協(xié)議、內(nèi)核版本在微信里打不開微信內(nèi)置瀏覽器權限策略限制測試原生瀏覽器排除問題必要時引導用系統(tǒng)瀏覽器打開有一個特別容易踩的坑getUserMedia在用戶點擊事件之外調(diào)用某些瀏覽器會直接拒絕授權彈窗。比如頁面加載后就自動調(diào)攝像頭Safari 可能不給彈權限框。解決辦法是把初始化攝像頭綁在“開始掃碼”按鈕的點擊事件里。4.2 識別率低畫面清晰度與光照的影響jsQR 的解碼效果高度依賴輸入圖像質量。最常見的識別失敗原因不是算法不行而是條碼在畫面里太小、太暗或者反光。實際調(diào)優(yōu)時可以參考這幾個方向距離引導頁面加一條輔助線提示用戶把條碼放在畫面中央?yún)^(qū)域。禁止縮放有些瀏覽器會自動對 video 做縮放導致條碼變虛。可以給 video 加object-fit: cover讓畫面鋪滿容器。裁剪識別區(qū)域優(yōu)先掃描畫面中央的條碼還可以預處理圖像比如去噪、增強對比度或做灰度化處理。jsQR 內(nèi)部會做灰度化但如果你在裁剪區(qū)域做了額外預處理比如用ctx.filter contrast(1.2)增強對比度在暗光環(huán)境下往往有意外驚喜。提示光線如果環(huán)境光不足建議在頁面上給出“光線不足”的提示。這個可以用視頻幀的平均亮度來判斷但不是必須根據(jù)自己的場景決定。4.3 瀏覽器原生掃碼 APIBarcodeDetector除了 jsQR瀏覽器現(xiàn)在提供了一個原生的BarcodeDetectorAPI可以直接識別條碼還支持指定碼制EAN-13、QR_CODE 等識別速度比純 JS 庫快不少。if (BarcodeDetector in window) { const detector new BarcodeDetector({ formats: [ean_13, code_128, qr_code] }); const barcodes await detector.detect(canvas); // barcodes[0].rawValue 就是識別結果 }但這個 API 目前最大的問題是兼容性參差不齊Chrome 桌面端和 Android 上支持較好iOS Safari 截至最近仍未完整支持微信內(nèi)置瀏覽器就更不一定了。我的建議是把 BarcodeDetector 當成一個漸進增強的能力優(yōu)先用 jsQR 保證全端一致檢測到支持 BarcodeDetector 時再切換過去。4.4 微信小程序和 App 嵌套 H5 的場景注意點看熱搜詞里很多人關心“H5 能不能調(diào)用微信小程序當前經(jīng)緯度”“小程序跳 H5 頁面”這類問題這里順帶說一下。H5 頁面在小程序 WebView 里運行時攝像頭權限策略和小程序原生組件完全是兩套邏輯。小程序的camera組件權限在小程序側H5 的getUserMedia權限在 WebView 側。如果你遇到在小程序里 H5 調(diào)不起攝像頭大概率是 WebView 沒有把攝像頭權限授權給頁面需要在 App 或小程序的 web-view 配置里處理。同樣App 里嵌套 H5 時Android 端的 WebView 需要在原生層申請CAMERA權限并且設置WebChromeClient.onPermissionRequest回調(diào)否則 H5 調(diào)用getUserMedia時會靜默失敗。這些問題前端單獨排查不出來得拉上客戶端開發(fā)一起聯(lián)調(diào)。4.5 頁面報錯排查技巧我把一些常見的報錯信息整理成了一個速查表方便大家快速定位報錯信息含義解決方向TypeError: Cannot read property getUserMedia of undefined瀏覽器不支持檢查 HTTPS、瀏覽器版本、內(nèi)核OverconstrainedError指定的 facingMode 無法滿足去掉exact限定NotReadableError攝像頭被其他程序占用關閉其他用到攝像頭的頁面或 AppAbortError用戶主動取消授權提示用戶重新授權在 button 點擊回調(diào)中重新調(diào)用 getUserMedia5. 關于性能優(yōu)化和用戶體驗的幾點心得最后分享一些交互層面的經(jīng)驗。別讓用戶自己點“開始”。很多掃碼頁面把攝像頭調(diào)用放在一個“開始掃碼”按鈕上這其實多了一步操作。用戶點進頁面目的就是掃碼直接在頁面加載后自動拉起攝像頭記得通過用戶手勢觸發(fā)比如監(jiān)聽點擊后調(diào)用配合一個半透明遮罩框提示“將條碼置于框內(nèi)”體驗順很多。識別成功要有明確的視覺和聲音反饋。視覺上可以做一個綠色的對勾框閃一下聲音上如果可以調(diào)用系統(tǒng)的震動或悅耳的提示音就更好。用戶掃完條碼如果在 200ms 內(nèi)沒看到任何反饋會下意識反復晃手機反而讓后續(xù)識別更困難。識別區(qū)域別占滿整個屏幕。對齊輔助框通常放在屏幕中部寬度約為屏幕的三分之二。這個區(qū)域內(nèi)識別準確率和速度最高。用戶把條碼對準框內(nèi)比整個屏幕胡亂晃動要穩(wěn)定得多。注意 H5 頁面在頁面切后臺時的處理。用visibilitychange事件在頁面隱藏時停止識別循環(huán)回到前臺時再恢復。否則用戶切到其他 App 再返回頁面還在瘋狂解碼耗電發(fā)熱不說還可能拿到一堆無效圖像。這一塊代碼很簡單但很能體現(xiàn)細節(jié)。6. 整套方案的最終形態(tài)把上面的步驟合在一起一個完整的 H5 掃碼頁面功能就成型了頁面加載后點擊按鈕調(diào)起getUserMedia視頻流實時預覽在video標簽中setInterval定時截幀到canvasjsQR解碼canvas圖像解碼成功后去重、回傳業(yè)務處理跳轉或停止攝像頭釋放視頻流。我后來把這套方案沉淀成了一個公共組件業(yè)務側只需要傳入“識別成功后做什么”的回調(diào)函數(shù)。目前已經(jīng)用在掃碼核銷、設備巡檢幾個項目里整體識別成功率在室內(nèi)光照環(huán)境下能穩(wěn)定在 98% 以上解碼耗時單幀大約 20~40ms用戶體驗是比較流暢的。有一點值得強調(diào)H5 掃碼方案本質上是“用瀏覽器能力模擬掃碼槍”它在便利性上有無可替代的優(yōu)勢但與原生掃碼在弱光、強反光等極端場景下仍有差距。如果你們的業(yè)務對識別率有極致要求比如密集貨架、大幅面的 Code128 標簽建議在前端方案之上再搭配原生掃碼組件兜底。兩者結合才是一個生產(chǎn)級掃碼功能的完整形態(tài)。本文還有配套的精品資源點擊獲取