HTML5 Web QR码扫描中相机自动对焦的完整实践指南

作者：袖梨 2026-07-10

本文详解如何在基于 navigator.mediaDevices.getUserMedia 的 Web QR 扫描应用中正确启用并验证相机自动对焦（focusMode），涵盖约束配置、设备兼容性判断、动态约束应用及常见失效原因分析。

本文详解如何在基于 `navigator.mediadevices.getusermedia` 的 web qr 扫描应用中正确启用并验证相机自动对焦（focusmode），涵盖约束配置、设备兼容性判断、动态约束应用及常见失效原因分析。

在 Web 端实现高精度 QR 码识别（尤其针对小尺寸或近距离目标）时，相机能否稳定对焦是关键瓶颈。你提供的代码尝试通过 advanced: [{ focusMode: "continuous" }] 启用连续对焦，但未生效——这并非代码逻辑错误，而是受限于浏览器、操作系统与硬件的协同支持层级。下面我们将从原理到实践，系统性解决该问题。

✅ 正确启用对焦：约束配置必须精准且分步验证

focusMode 属于 高级媒体约束（Advanced Constraints），但其可用性高度依赖设备能力与浏览器实现。首先需确认设备是否真正支持：

// 1. 检查浏览器是否声明支持 focusModeconst supported = navigator.mediaDevices.getSupportedConstraints();console.log('focusMode supported?', !!supported.focusMode); // ✅ 必须为 true// 2. 获取实际可用的 focusMode 值（可能为 'manual', 'auto', 'continuous' 等）const track = stream.getVideoTracks()[0];const capabilities = track.getCapabilities();console.log('focusMode capabilities:', capabilities.focusMode); // 如 ["auto", "continuous"]

⚠️ 注意：getCapabilities() 仅在媒体流已激活（即 srcObject 已设置且 play() 调用后）才返回有效值；在 getUserMedia 回调内立即调用可能返回 undefined。

✅ 动态应用约束：避免 advanced 嵌套错误，使用标准字段

你代码中混用了两种约束写法（video: { advanced: [...] } 和顶层 advanced），且 focusMode 应作为一级约束项，而非嵌套在 advanced 数组中（该语法已废弃）。正确写法如下：

立即学习“前端免费学习笔记（深入）”；

const constraints = {  video: {    width: { ideal: 1280 },    height: { ideal: 720 },    facingMode: 'environment',    focusMode: 'continuous', // ✅ 直接设为字符串（非 advanced 数组）    frameRate: { ideal: 15 }  }};navigator.mediaDevices.getUserMedia(constraints)  .then(stream => {    const track = stream.getVideoTracks()[0];    // ? 关键：在流播放后，再尝试 applyConstraints（确保 track 已就绪）    video.srcObject = stream;    return video.play().then(() => {      // 等待视频渲染帧就绪（可加 setTimeout 或监听 loadeddata）      return new Promise(resolve => setTimeout(resolve, 300));    }).then(() => {      // 此时 applyConstraints 才更可靠      return track.applyConstraints({        focusMode: 'continuous'      });    });  })  .then(() => console.log('Focus mode applied successfully'))  .catch(err => console.warn('Failed to set focusMode:', err.name, err.message));

⚠️ 兼容性现实：并非所有设备/浏览器都支持 focusMode

✅ 支持较好：Chrome for Android（部分旗舰机型）、Safari on iOS 16.4+（需 HTTPS + 用户手势触发）、Edge on Windows（Surface 设备）
❌ 普遍不支持：大部分桌面摄像头（无自动对焦马达）、旧版 Android WebView、部分低端手机浏览器
? 实测发现：即使 getCapabilities() 返回 ["continuous"]，部分 Android 设备仍静默忽略该设置——这是底层 HAL 层限制，前端无法绕过。

✅ 提升小码识别率的替代策略（当对焦不可用时）

若 focusMode 确认不可用，应转向软件层优化：

增大采集分辨率 + ROI 裁剪
使用更高分辨率（如 1920x1080）采集，再 drawImage 裁剪中心区域，提升像素密度：
```
context.drawImage(video,   (video.videoWidth - 600) / 2,   (video.videoHeight - 600) / 2,   600, 600,   0, 0, 600, 600);
```

启用 HDR 与降噪（如支持）

exposureMode: 'continuous',whiteBalanceMode: 'continuous',noiseReduction: true

QR 解码增强
使用 jsQR 的 inversionAttempts 和 numWorkers 提升鲁棒性：

const code = jsQR(imageData.data, imageData.width, imageData.height, {  inversionAttempts: "dontInvert", // 或 "both"  numWorkers: 2});

✅ 最佳实践总结

✅ 必做三步：检查 getSupportedConstraints() → 获取 getCapabilities() → applyConstraints() 在 video.play() 后调用
✅ 使用 focusMode: "continuous"（非数组形式），避免 advanced 字段
✅ 对焦失败时，优先优化采集分辨率、ROI 区域和解码参数，而非强依赖硬件对焦
✅ 生产环境务必添加降级提示：“当前设备不支持自动对焦，请保持 QR 码距离镜头 20–40 cm 并确保光线充足”

通过以上方法，你将显著提升 Web QR 扫描在真实设备上的可用性与识别成功率。记住：Web 媒体 API 的能力边界由硬件定义，而优雅降级才是专业体验的核心。