HTML5 Web QR码扫描实现相机自动对焦实践指南

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

在 Web 端实现高精度 QR 码识别时，尤其是针对小尺寸或近距离目标，相机能否稳定对焦，往往是决定成败的关键瓶颈。不少开发者尝试通过 advanced: [{ focusMode: "continuous" }] 来启用连续对焦，结果却发现毫无效果——这里需要明确的是，这并不是代码逻辑本身的问题，而是受限于浏览器、操作系统与硬件这三层之间的协同支持深度。下面我们就从原理到实践，系统地拆解这个问题。

先说一个小知识点。focusMode 属于高级媒体约束（Advanced Constraints），但它的可用性高度依赖设备能力与浏览器实现。因此，第一步并不是直接写约束，而是先确认设备是否真正支持它。

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

要验证支持情况，需要分两步走：

// 1. 检查浏览器是否声明支持 focusMode
const 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 不可用，那就必须转向软件层来优化了。这里提供几个经过验证的策略：

1. 增大采集分辨率 + ROI 裁剪
   使用更高分辨率（比如 1920x1080）采集，再通过 drawImage 裁剪出中心区域，可以显著提升目标区域的像素密度：

   context.drawImage(video, 
     (video.videoWidth - 600) / 2, 
     (video.videoHeight - 600) / 2, 
     600, 600, 
     0, 0, 600, 600);

2. 启用 HDR 与降噪（如果支持的话）

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

3. 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 的能力边界是由硬件定义的，而优雅降级，才是专业体验的核心。