JS实现网页摄像头实时扫码：结合getUserMedia与jsQR教程

一、为什么采用 getUserMedia 搭配 jsQR？

早期网页识别二维码常依赖用户上传图片（<input type="file">），再进行静态解析。这种方式打断了用户操作链路，无法像原生 App 一样实现“对准即扫”的即时反馈。要在现代浏览器内实现实时连续检测，前端需要构建一条完整的图像流水线：硬件采集、视频承载、帧缓存抽取与算法解码。

在众多技术方案中，getUserMedia 负责规范化地访问终端摄像头，抹平不同设备平台的硬件底层差异；而 jsQR 是一个专为 Web 环境设计的开源纯 JavaScript 解码库，其优势在于无需 WebAssembly 辅助加载、体积小巧（压缩后仅约 40KB）、支持容错纠错，且能直接消费由 Canvas 提取出的原始一维 RGBA 像素矩阵（ImageData.data）。二者结合，构成了纯前端无后端依赖的实时扫码核心标准模式。

二、运行环境与准备工作

在着手编写逻辑之前，必须满足现代浏览器对多媒体采集的安全限制，并准备必要的 DOM 载体与脚本依赖。

1. 安全上下文限制（HTTPS 协议）

出于用户隐私与安全策略，W3C 规范要求 navigator.mediaDevices.getUserMedia 只能在安全上下文（Secure Context）中被调用。这意味着：

• 本地开发：仅允许在 http://localhost 或 http://127.0.0.1 域名下直接调试摄像头；
• 局域网或远程部署：必须配置有效的 SSL 证书并通过 https:// 协议访问。在未配置证书的普通 HTTP 局域网 IP（如 http://192.168.1.100）下，navigator.mediaDevices 将直接为 undefined，导致功能无法运行。

2. 引入 jsQR 库

你可以通过公共 CDN 直接在 HTML 中引入编译好的脚本，也可以在现代工程化脚手架（如 Vite、Webpack）中通过 npm 安装：

<!-- CDN 静态脚本引入方式 -->
<script src="https://cdn.jsdelivr.net/npm/jsqr@1.4.0/dist/jsQR.js"></script>

如果使用 npm 管理依赖，可执行 npm install jsqr，并在模块中通过 import jsQR from "jsqr"; 进行导入。

3. HTML 骨架准备

实时扫描界面需要三个核心 DOM 元素：用于接收摄像头视频流的 <video>、用于抽帧与绘制定位线的 <canvas>，以及展示结果的文本提示区：

<div class="scanner-container">
  <!-- 移动端必须包含 playsinline 属性，防止 iOS 弹出系统全屏播放器 -->
  <video id="qr-video" playsinline muted autoplay style="display: none;"></video>
  <canvas id="qr-canvas"></canvas>
  <div id="qr-result">正在寻找二维码...</div>
</div>

三、分步实现：从拉取视频流到闭环解析

整个识别流程可拆解为四个具体步骤：获取后置摄像头流、同步视频就绪时机、Canvas 图像捕获与 jsQR 解析、绘制识别反馈框。

步骤 1：申请摄像头权限并绑定媒体流

移动端扫码通常需要调用设备的后置摄像头。在约束参数中，使用 facingMode: "environment" 指定使用外向/后置摄像头。为确保在不同机型上的最大兼容性，建议使用推荐约束而非强制严格约束。

const video = document.getElementById("qr-video");

async function startCamera() {
  try {
    const constraints = {
      video: {
        facingMode: "environment", // 优先请求后置摄像头
        width: { ideal: 1280 },
        height: { ideal: 720 }
      }
    };
    const stream = await navigator.mediaDevices.getUserMedia(constraints);
    video.srcObject = stream;
    // 显式触发播放
    await video.play();
    requestAnimationFrame(tick);
  } catch (err) {
    console.error("无法访问摄像头:", err);
    document.getElementById("qr-result").innerText = "摄像头访问失败：" + err.message;
  }
}

步骤 2：监控视频就绪状态（解决黑屏与尺寸为0）

调用 video.play() 之后，视频帧数据并不会立即解码完成。如果立即从 <video> 中提取画面，会导致 videoWidth 和 videoHeight 为 0，绘制出的像素全为透明黑屏。

因此，必须通过 video.readyState === video.HAVE_ENOUGH_DATA（数值为 4）判断当前帧是否已具备足够的渲染数据。只有在此条件满足时，才将 Canvas 的物理宽高与视频实际像素同步，并执行图像抓取：

const canvas = document.getElementById("qr-canvas");
const ctx = canvas.getContext("2d");

function checkAndResizeCanvas() {
  if (video.readyState === video.HAVE_ENOUGH_DATA) {
    if (canvas.width !== video.videoWidth) {
      canvas.width = video.videoWidth;
      canvas.height = video.videoHeight;
    }
    return true;
  }
  return false;
}

步骤 3：抽取像素并交由 jsQR 解码

借助 ctx.drawImage() 将当前视频画面绘制到 Canvas 画布中，再通过 ctx.getImageData() 获取包含一维 RGBA 数组的图像数据对象，最后传入 jsQR(imageData.data, width, height) 尝试解析：

function tick() {
  if (checkAndResizeCanvas()) {
    // 1. 将视频当前帧刷入画布
    ctx.drawImage(video, 0, 0, canvas.width, canvas.height);
    
    // 2. 抓取画布的完整一维 RGBA 像素矩阵
    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    
    // 3. 执行二维码定位识别与解码
    const code = jsQR(imageData.data, imageData.width, imageData.height, {
      inversionAttempts: "dontInvert" // 多数场景无需反转黑白反色，提升识别速度
    });

    if (code) {
      // 成功识别到二维码
      drawLine(code.location.topLeftCorner, code.location.topRightCorner, "#71A397");
      drawLine(code.location.topRightCorner, code.location.bottomRightCorner, "#71A397");
      drawLine(code.location.bottomRightCorner, code.location.bottomLeftCorner, "#71A397");
      drawLine(code.location.bottomLeftCorner, code.location.topLeftCorner, "#71A397");

      document.getElementById("qr-result").innerText = "识别成功: " + code.data;
      // 业务处理逻辑：如需单次扫码，可在此处中止循环并释放摄像头
    }
  }
  // 继续下一帧循环
  requestAnimationFrame(tick);
}

步骤 4：在 Canvas 上高亮追踪边框

jsQR 解析成功后，会返回包含四个角点几何坐标的 location 对象（包含 topLeftCorner、topRightCorner、bottomRightCorner 与 bottomLeftCorner）。通过在 Canvas 上连接这四个点，可以为用户提供直观的目标捕获视觉反馈：

function drawLine(begin, end, color) {
  ctx.beginPath();
  ctx.moveTo(begin.x, begin.y);
  ctx.lineTo(end.x, end.y);
  ctx.lineWidth = 4;
  ctx.strokeStyle = color;
  ctx.stroke();
}

四、完整独立可运行示例

以下提供包含样式美化、摄像头异常回退、高亮框绘制以及主动关闭摄像头流的完整单一文件范例。可将其直接保存为本地 HTML 文件，通过本地静态服务器启动测试：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>实时扫码演示</title>
  <script src="https://cdn.jsdelivr.net/npm/jsqr@1.4.0/dist/jsQR.js"></script>
  <style>
    body {
      font-family: sans-serif;
      margin: 0;
      padding: 20px;
      display: flex;
      flex-direction: column;
      align-items: center;
      background: #F3F6FA;
    }
    .scanner-box {
      position: relative;
      width: 100%;
      max-width: 500px;
      border-radius: 12px;
      overflow: hidden;
      box-shadow: 0 4px 12px rgba(0,0,0,0.1);
      background: #000;
    }
    #qr-canvas {
      width: 100%;
      height: auto;
      display: block;
    }
    .status-card {
      margin-top: 16px;
      padding: 12px 20px;
      background: #FFFFFF;
      border-radius: 8px;
      font-size: 14px;
      color: #243342;
      width: 100%;
      max-width: 500px;
      word-break: break-all;
    }
    button {
      margin-top: 12px;
      padding: 10px 18px;
      background: #6B88A6;
      color: #FFF;
      border: none;
      border-radius: 6px;
      font-size: 14px;
      cursor: pointer;
    }
  </style>
</head>
<body>
  <div class="scanner-box">
    <video id="video" playsinline muted autoplay style="display:none;"></video>
    <canvas id="canvas"></canvas>
  </div>
  <div class="status-card" id="output">等待开启摄像头...</div>
  <button id="btn-toggle" onclick="toggleScan()">启动扫描</button>

  <script>
    let videoStream = null;
    let animationId = null;
    const video = document.getElementById("video");
    const canvas = document.getElementById("canvas");
    const ctx = canvas.getContext("2d", { willReadFrequently: true });
    const output = document.getElementById("output");
    const btn = document.getElementById("btn-toggle");

    async function toggleScan() {
      if (videoStream) {
        stopScan();
      } else {
        await startScan();
      }
    }

    async function startScan() {
      output.innerText = "正在请求摄像头授权...";
      try {
        // 优先后置镜头，若失败回退至任意视频流
        let constraints = { video: { facingMode: "environment" } };
        try {
          videoStream = await navigator.mediaDevices.getUserMedia(constraints);
        } catch (e) {
          console.warn("后置镜头请求受限，尝试默认镜头回退", e);
          videoStream = await navigator.mediaDevices.getUserMedia({ video: true });
        }

        video.srcObject = videoStream;
        await video.play();
        btn.innerText = "停止扫描";
        output.innerText = "正在实时扫描中...";
        animationId = requestAnimationFrame(scanLoop);
      } catch (err) {
        output.innerText = "启动失败: " + err.message;
      }
    }

    function scanLoop() {
      if (video.readyState === video.HAVE_ENOUGH_DATA) {
        if (canvas.width !== video.videoWidth) {
          canvas.width = video.videoWidth;
          canvas.height = video.videoHeight;
        }
        ctx.drawImage(video, 0, 0, canvas.width, canvas.height);
        const imgData = ctx.getImageData(0, 0, canvas.width, canvas.height);
        const code = jsQR(imgData.data, imgData.width, imgData.height, {
          inversionAttempts: "dontInvert"
        });

        if (code) {
          // 标记定位角标
          drawBox(code.location);
          output.innerHTML = "<strong style='color:#71A397'>解析内容：</strong>" + code.data;
        }
      }
      animationId = requestAnimationFrame(scanLoop);
    }

    function drawBox(loc) {
      ctx.beginPath();
      ctx.moveTo(loc.topLeftCorner.x, loc.topLeftCorner.y);
      ctx.lineTo(loc.topRightCorner.x, loc.topRightCorner.y);
      ctx.lineTo(loc.bottomRightCorner.x, loc.bottomRightCorner.y);
      ctx.lineTo(loc.bottomLeftCorner.x, loc.bottomLeftCorner.y);
      ctx.closePath();
      ctx.lineWidth = 4;
      ctx.strokeStyle = "#71A397";
      ctx.stroke();
    }

    function stopScan() {
      if (animationId) cancelAnimationFrame(animationId);
      if (videoStream) {
        videoStream.getTracks().forEach(track => track.stop());
        videoStream = null;
      }
      video.srcObject = null;
      ctx.clearRect(0, 0, canvas.width, canvas.height);
      btn.innerText = "启动扫描";
      output.innerText = "摄像头已关闭";
    }
  </script>
</body>
</html>

五、移动端实战陷阱与性能优化

在实际生产部署中，单纯运行基础代码往往会在特定机型上遭遇发热卡顿、摄像头打开报错或 iOS 强制全屏等问题。针对这些情况，需要落实以下针对性优化：

1. 摄像头参数配置：避免 exact 强约束报错

部分教程推荐书写 facingMode: { exact: "environment" }。在规范中，exact 代表强制精确匹配。如果用户设备只有单摄、系统底层未映射环境参数，或浏览器权限受限，该调用会直接抛出 OverconstrainedError 异常导致逻辑中断。

2. 降低解析频率与采样分辨率（降温省电）

在移动设备上，以 60 FPS 逐帧执行 getImageData 和 jsQR 算法会产生极高的计算开销，导致手机在 1-2 分钟内发烫掉电。实际上，人眼视觉对 15 FPS 的画面响应已足够灵敏，无需每帧进行图像特征计算。

• 时间戳节流：记录上一次解析时间戳，限制 jsQR() 的触发间隔为 60~100 毫秒（约 10~15 FPS）。
• 下采样解析：若视频物理分辨率高达 1920×1080，可创建一个隐藏的较小 Canvas（如限宽 640px）专门用于数据提取，大幅减少需要遍历的像素数组长度。
• Canvas 优化属性：在获取 2D 绘图上下文时，配置 { willReadFrequently: true }，提示浏览器优化只读缓冲，显著加快 getImageData 的吞吐速度。

3. iOS Safari 的 playsinline 与静音策略

在 iOS Safari 中，默认情况下媒体播放会尝试接管系统原生全屏播放器。一旦触发全屏，Canvas 将无法继续在其上层正常渲染，抽帧管线也会被暂停。

必须确保为 <video> 标签添加 playsinline、webkit-playsinline 以及 muted 属性，确保视频流在网页文档流内静默播放。

六、方案全景与工程化落地总结

通过结合 getUserMedia、Canvas 抽帧与 jsQR，前端开发者能够在无原生插件支持的纯网页环境下，构建出毫秒级响应的实时扫码体验。

在实际项目集成时，建议将上述逻辑封装为一个具有完整生命周期（mount、start、stop、destroy）的独立组件。在识别成功触发回调或页面路由发生跳转时，务必遍历视频流的 stream.getTracks() 并显式调用 track.stop()，确保物理摄像头指示灯及时熄灭，避免造成安全隐患与内存泄漏。