如何正确使用 srcObject 播放用户媒体流（如摄像头视频）

2026年2月13日 星耀云

如何正确使用 srcObject 播放用户媒体流（如摄像头视频）

本文详解在 HTML 元素中正确设置 srcObject 属性以显示摄像头画面的关键要点，重点解决因忽略 Promise 异步特性导致的 TypeError 和 404 错误，并提供可直接运行的现代 JavaScript 实现方案。

本文详解在 html `

在 WebRTC 开发中，将用户摄像头视频实时渲染到

  • Failed to set the ‘srcObject’ property… The provided value is not of type ‘(MediaSourceHandle or MediaStream)’
  • GET http://127.0.0.1:5500/[object%20Promise] 404 (Not Found)

这两个错误的根本原因高度一致：误将 navigator.mediaDevices.getUserMedia() 返回的 Promise 对象直接赋值给 video.srcObject（而非等待其解析后的 MediaStream 实例）。

getUserMedia() 是一个异步 API，始终返回 Promise —— 它不是立即可用的流，而是一个“未来才会兑现的承诺”。若直接写 video.srcObject = navigator.mediaDevices.getUserMedia(…)，实际赋值的是 Promise 对象本身，而 srcObject 仅接受 MediaStream 或 MediaSource 类型，故触发第一个 TypeError；若错误地尝试用 video.src = … 赋值该 Promise，则浏览器会将其 .toString()（即 “[object Promise]”）拼接为 URL，引发第二个 404。

✅ 正确做法是：通过 .then() 链或 await 等待 Promise 解析后，再将获得的 MediaStream 赋给 video.srcObject。

以下为推荐的两种生产就绪写法（均兼容现代浏览器，含错误处理与 DOM 就绪保障）：

✅ 方案一：.then() 链式调用（简洁、无 async/await）

<!DOCTYPE html> <html lang="zh-CN"> <head>   <meta charset="UTF-8">   <meta name="viewport" content="width=device-width, initial-scale=1.0">   <title>摄像头视频流演示</title> </head> <body>   <main>     <h2>实时摄像头预览</h2>     <video id="retourUtilisateur" autoplay playsinline muted width="640" height="480"></video>     <p id="status">正在初始化...</p>   </main>   <script>     const constraints = {       video: {         width: { min: 1280, ideal: 1920, max: 2560 },         height: { min: 720, ideal: 1080, max: 1440 }       }     };      const video = document.getElementById('retourUtilisateur');     const status = document.getElementById('status');      // 检查 API 可用性（可选但推荐）     if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {       status.textContent = '❌ 浏览器不支持 getUserMedia API';       throw new Error('MediaDevices API not supported');     }      // 获取并绑定媒体流     navigator.mediaDevices.getUserMedia(constraints)       .then(stream => {         status.textContent = '✅ 摄像头已连接，视频流加载中...';         video.srcObject = stream; // ✅ 此处 stream 是 MediaStream 实例       })       .catch(err => {         status.textContent = `❌ 访问摄像头失败：${err.name || '未知错误'}`;         console.error('Camera access error:', err);       });   </script> </body> </html>

✅ 方案二：async/await + IIFE（更符合现代 JS 习惯）

// 确保脚本在 DOM 加载完成后执行（推荐加 defer 属性） document.addEventListener('DOMContentLoaded', async () => {   const video = document.getElementById('retourUtilisateur');   const status = document.getElementById('status');    const constraints = { video: { width: 1280, height: 720 } };    try {     const stream = await navigator.mediaDevices.getUserMedia(constraints);     status.textContent = '✅ 摄像头流已成功绑定';     video.srcObject = stream;   } catch (err) {     status.textContent = `❌ 启动失败：${err.message}`;     console.error(err);   } });

? 关键注意事项：

  • srcObject 是标准属性：自 Chrome 53、Firefox 50、Safari 11+ 起已广泛支持（MDN 兼容性表），无需回退到 src + URL.createObjectURL()（后者已过时且需手动释放）；
  • 避免 video.src = stream：src 属性只接受字符串 URL（如 MP4 地址），对 MediaStream 无效，强行赋值会触发 404；
  • 务必添加 autoplay 和 playsinline：尤其在 iOS Safari 中，缺失 playsinline 会导致全屏播放无法自动启动；
  • 权限与安全上下文：getUserMedia() 必须在安全上下文（HTTPS 或 localhost）中调用，否则直接拒绝；
  • 流释放建议：页面卸载前应调用 stream.getTracks().forEach(track => track.stop()) 避免后台持续采集。

掌握 Promise 的异步本质与 srcObject 的类型契约，是驾驭 WebRTC 媒体流的第一道门槛。以上代码可直接运行于本地服务器（如 VS Code Live Server），无需额外依赖，助你快速构建稳定可靠的音视频应用基础。