本文详解如何在基于 navigator.mediaDevices.getUserMedia 的 Web QR 扫描应用中正确启用并验证相机自动对焦（focusMode），涵盖约束配置、设备兼容性判断、动态约束应用及常见失效原因分析。
本文详解如何在基于 `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 确认不可用，应转向软件层优化：
-
增大采集分辨率 + 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 的能力边界由硬件定义，而优雅降级才是专业体验的核心。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
