Barcode Detection API 功能强大，但许多前端开发者在第一步就遇到阻碍——直接将 detect()，结果往往是静默失败或抛出异常。这并非 API 本身的问题，而是其对输入源有严格限制。只有四种图像源被允许：ImageBitmap、HTMLCanvasElement、OffscreenCanvas 或 VideoFrame。由于 DOM 中的 NotAllowedError 错误。
为什么直接传 ![]()
detect() 会失败
许多开发者忽略了几个关键细节。首先，图片的加载状态至关重要——img.complete 必须为 true，否则 drawImage 无法绘制任何内容，后续所有操作都将无效。其次，跨域问题需提前处理：若图片来自 CDN 或其他域名，必须设置 img.crossOrigin = 'anonymous'，否则 canvas 会被标记为“被污染”，导致 transferToImageBitmap() 报错。最后，canvas 的宽高必须精确匹配 img.naturalWidth 和 img.naturalHeight，任何拉伸或缩放都会明显降低识别成功率。
ImageBitmap 两种生成方式怎么选
生成 ImageBitmap 有两种主流方式：canvas.transferToImageBitmap() 和 createImageBitmap(canvas)。前者是推荐方法，性能更优，因为它直接将 canvas 内存“移交”给 ImageBitmap，无需复制像素数据，内存控制更佳。后者兼容性稍高（Chrome 52+ 即可支持），但可能带来额外的解码开销。
实际差异在移动端尤为明显。Android Chrome 90+ 对 transferToImageBitmap 支持良好，但部分旧版本 WebView 可能不兼容，此时需回退到 createImageBitmap。实用策略是：优先使用 transferToImageBitmap，配合 try/catch 捕获异常，再降级到 createImageBitmap(canvas)。另外需注意，不要直接用 createImageBitmap(img) 转换 DOM 图片，它仍受跨域限制且无法保证尺寸精度，是最容易出错的写法。
检测失败时最该检查的三个硬性条件
检测返回空数组并不表示 API 出现问题，很可能是输入图像未达到最低质量门槛。Barcode Detection API 不进行图像增强，完全依赖原始像素匹配。
第一个条件是物理宽度。条码在 canvas 上的实际宽度建议不低于 100px（针对 EAN/UPC 类）或 120px（针对 QR 码），过小则直接被忽略。第二个条件是倾斜角度，若超过 ±15°，漏检概率会急剧上升，尤其是 QR 码的四个角点模糊时，几乎无法定位。第三个条件是对比度，如果背景过浅（如浅灰底配白色条码）、存在严重反光或阴影遮挡超过 30%，特征点提取将失败。
实用的调试技巧：使用 canvas.toDataURL('image/png') 截取一帧保存，肉眼检查条码是否清晰、居中且无畸变。很多时候问题并非出在代码，而是图片本身质量不足。
格式列表写错一个字母就整个 detector 初始化失败
创建 BarcodeDetector 实例时，formats 数组不能为空，且每个值必须严格符合规范。例如，二维码格式必须写作 "qr_code"，而不是 "qrcode"、"QR_CODE" 或 "qr"。一旦写错，浏览器会抛出 TypeError: format list must not be empty——即便数组非空，由于值非法，也会被视为空列表。
那么，哪些格式可用？以 detector.getSupportedFormats() 返回结果为准。Chrome 103+ 支持 ["qr_code", "ean_13", "code_128", "upc_a", "itf", "codabar"] 等常见格式。注意，格式名区分大小写，下划线不可省略。若只需识别二维码，仅传入 ["qr_code"] 即可，减少格式列表可略微降低检测延迟，在移动端效果更佳。
此外，还有一个现实问题：该 API 在 Safari 和 Firefox 中永远不可用。即使进行 feature detection，'BarcodeDetector' in window 始终返回 false。不要尝试使用 polyfill 或强制启用，目前它仅适用于基于 Chromium 的浏览器——认清这一边界，比解决所有技术细节更为重要。