H5原生调用摄像头全攻略：从getUserMedia到移动端适配

先说一个我自己的真实经历。之前做移动端H5项目页面需要直接用浏览器能力打开摄像头做人像采集。第一版Demo在电脑Chrome上跑结果白屏控制台日志打出一个NotAllowedError。我第一反应是权限被浏览器拦了排查一圈下来才发现页面跑在 http 局域网地址上浏览器根本不信任明文协议下的摄像头访问。换成 https 之后画面秒出。那次之后我才意识到getUserMedia表面看就一个方法的事真正麻烦的是它背后一整套安全模型、约束规则和兼容性细节。这篇文章就把 H5 原生调用摄像头这件事完整拆开讲从最小可用实现到移动端适配再到线上排障把我踩过的坑和验证过的方案都写出来给正准备接摄像头的同学做参考。1. 先从一次黑屏调试说起getUserMedia 是什么凭什么能调摄像头1.1 我的第一步就翻车了拿不到摄像头的原因那次报错场景是这样的页面本身逻辑很简单一个video标签一段getUserMedia调用打开就黑屏。控制台显示NotAllowedError: Permission denied。当时我下意识以为是用户没授权因为浏览器弹了权限框我没点“允许”所以报错。但我反复点了允许依然失败。后来把页面从 http 换成 https 才恍然大悟Chrome 把摄像头、麦克风、地理位置这类高危能力全部锁在“安全上下文”里。只有在 HTTPS 页面、本地localhost或127.0.0.1页面里navigator.mediaDevices才存在并且可用。如果页面跑在纯 http 下navigator.mediaDevices直接是undefined而你调用getUserMedia时大概率会得到TypeError或者NotAllowedError具体表现因浏览器版本而异。这个门槛看起来简单但真线上出问题时很多人第一反应是去查权限配置很少有人先怀疑协议。尤其是内网联调阶段一堆人拿局域网 IP 地址在手机上测摄像头百思不得其解。记住一句话摄像头不受信明文 http 页面没有资格拿它。线上环境必须是 HTTPS本地调试优先用localhost。1.2 getUserMedia 的底层逻辑和安全限制getUserMedia是 W3C 定义的 MediaDevices 接口里的核心方法调用的是浏览器的媒体采集能力不依赖任何第三方 SDK。它返回一个 Promise成功时 resolve 一个MediaStream对象失败时 reject 一个DOMException。从浏览器内部看整个过程大致分四步校验页面所在上下文是否安全HTTPS、localhost。检查页面是否有摄像头权限没有权限就拉起系统授权弹窗。根据调用方传入的 constraints 约束去匹配底层设备。匹配成功后建立采集通道把实时媒体流交给网页。这里特别要注意“用户手势”的问题。浏览器对权限弹窗的触发有严格限制某些浏览器要求getUserMedia必须在用户点击、触摸等手势事件里调用否则可能直接拒绝或者静默失败。我见过最典型的场景是页面一加载就在DOMContentLoaded里自动调用摄像头PC 端表现得还好Android 部分浏览器直接不发权限弹窗。稳妥的做法是把摄像头打开动作绑定到一个明确的按钮点击事件上。1.3 返回结果与异常的全家族Promise成功之后拿到的MediaStream是一个媒体轨道集合。视频轨道是一个或多个MediaStreamTrack类型是video对应摄像头音频轨道类型是audio对应麦克风。你可以通过stream.getVideoTracks()拿到视频轨道数组通常只有一个就是当前使用的摄像头。失败时的DOMException名字是排查问题最重要的线索。我把常见错误整理成一张表遇到报错直接对照错误名称含义常见触发场景NotAllowedError用户拒绝授权或页面安全策略禁止权限弹窗被拒绝、iframe 缺少allowcamera、HTTP 非安全上下文NotFoundError没有找到匹配的摄像头设备电脑没插摄像头、虚拟机里没分配摄像头、约束条件指定了不存在的设备NotReadableError硬件被占用无法读取摄像头正被原生相机 App 或其他标签页占用OverconstrainedError约束条件过强没有设备满足同时指定了exact分辨率又指定了不兼容的aspectRatioTypeError参数格式错误constraints 不是对象或者 video 和 audio 同时省略我见过的绝大部分线上问题都落在NotAllowedError和OverconstrainedError这两类。前者是安全模型问题后者是约束写法问题。后面章节会分别展开。2. 最小可用实现从拿到流到画面出现参数与错误全解析2.1 一套最小可跑的完整页面先给出一段最简代码不玩花活。一个按钮触发打开摄像头一个video标签显示画面一个按钮关闭摄像头video idpreview autoplay playsinline muted/video button idopenBtn打开摄像头/button button idcloseBtn关闭摄像头/buttonconst videoEl document.getElementById(preview); async function openCamera() { if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) { alert(当前浏览器不支持摄像头调用请使用最新版 Chrome/Safari/Edge); return; } try { const stream await navigator.mediaDevices.getUserMedia({ video: true, audio: false }); videoEl.srcObject stream; await videoEl.play().catch(() {}); // 手动触发播放兼容移动端自动播放限制 } catch (err) { console.error([摄像头] 打开失败:, err.name, err.message); } } function closeCamera() { if (videoEl.srcObject) { videoEl.srcObject.getTracks().forEach((track) track.stop()); videoEl.srcObject null; } } document.getElementById(openBtn).addEventListener(click, openCamera); document.getElementById(closeBtn).addEventListener(click, closeCamera);这套代码有几个关键点全是经验换来的videoEl.srcObject stream是如今唯一推荐的赋值方式。早期有人用URL.createObjectURL(stream)生成一个临时地址塞给src这个方法已经被新版本浏览器废弃不要再写。video标签上autoplay和muted缺一不可移动端浏览器有自动播放策略带声音的视频不允许自动播放所以预览画面必须静音否则打开摄像头后画面停在第一帧。playsinline是给 iOS Safari 看的不加它视频会被强制进入全屏播放模式页面内嵌预览失效。videoEl.play()返回一个 Promise在某些浏览器里如果 autoplay 没被放行这个 Promise 会 reject所以要加.catch()防止报未捕获错误。整段代码真正在摄像头采集层面的逻辑只有getUserMedia一行但外面这些“配套设施”才是页面能不能正常跑起来的关键。2.2 约束参数怎么写给才合理getUserMedia的 constraints 参数是踩坑重灾区。很多人图省事直接写{ video: true }这在功能上没问题但没发挥约束的价值也有人一上来就写{ video: { width: { exact: 1920 }, height: { exact: 1080 } } }结果直接OverconstrainedError。约束系统的核心概念是你给的每个属性通常是一个“理想区间”浏览器在硬件能力范围内做匹配而不是精确执行。const stream await navigator.mediaDevices.getUserMedia({ video: { width: { ideal: 1280, max: 1920 }, height: { ideal: 720, max: 1080 }, frameRate: { ideal: 30, max: 30 }, facingMode: user // 优先前置摄像头 }, audio: false });ideal表示理想值浏览器会优先选最接近该值的能力max表示上限min表示下限exact表示必须精确匹配非匹配不可就报OverconstrainedError。我的建议是业务场景里尽量避免使用exact。比如要拍身份证照片希望高清一点就写ideal: 1920加上一个合理上限没必要精确锁定 1920x1080因为部分安卓机器主摄只支持 4:3 尺寸你指定 16:9 的 exact 就废了。想让预览流畅就显式限制frameRate的上限为 30。不写帧率某些设备默认输出 60fps信号是流畅了但页面解码开销和发热量都成倍上涨这是移动端性能问题的主要来源之一。facingMode是控制前后摄最常用的属性取值有user前置、environment后置还有left、right但后两个很少用。注意它表达的是“倾向”不是精确选择。环境里只有一个摄像头时你传environment它也会用唯一那个。想精确指定设备用下面会讲到的deviceId。2.3 拿到流之后video 绑定与真实参数核对拿到MediaStream后我建议养成一个习惯立刻打印一下真实参数别盲信自己写的 constraints。const videoTrack stream.getVideoTracks()[0]; const settings videoTrack.getSettings(); console.log([摄像头] 真实参数:, { deviceId: settings.deviceId, width: settings.width, height: settings.height, frameRate: settings.frameRate, facingMode: settings.facingMode });track.getSettings()返回的是浏览器最终协商出来的实际采集参数。当你怀疑“为什么我明明指定了 720p 结果视频是 480p”或者“为什么画面比例不对”的时候这个接口是最直接的证据。我在排查线上问题时几乎每次都先让现场人员打印这段日志很多疑难杂症的根因一眼就能看出来。打个比方getUserMedia的 constraints 像你下馆子点菜说“少放辣”厨师会根据食材和灶台能力做出一个“他认为符合要求的”菜而不是完全精确执行。getSettings()就是端上来的那道菜你只有看到它才知道最终成品是什么。3. 拍照与录像把媒体流变成业务能力的两种姿势3.1 用 canvas 截帧拍照的关键细节打开了摄像头画面也在 video 标签里显示了但很多业务要的是“把这一刻存成一张照片”。标准做法是用canvas截取视频帧。function capturePhoto() { const canvas document.createElement(canvas); canvas.width videoEl.videoWidth; canvas.height videoEl.videoHeight; const ctx canvas.getContext(2d); ctx.drawImage(videoEl, 0, 0, canvas.width, canvas.height); canvas.toBlob((blob) { const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download photo_${Date.now()}.jpg; a.click(); URL.revokeObjectURL(url); }, image/jpeg, 0.92); }这里最关键的细节是canvas.width和canvas.height必须用videoEl.videoWidth和videoEl.videoHeight而不是 CSS 宽高。CSS 宽高是布局后的显示尺寸videoWidth才是视频帧的真实像素宽度。如果你用 CSS 尺寸去建 canvas画出来的图大概率被裁剪或者比例错乱。那“为什么拍出来的照片人脸是歪的/被拉长了”通常是因为业务想要一个固定比例比如身份证件的 1:1 照片但摄像头输出是 4:3 或 16:9。直接把整个视频帧塞进目标尺寸会变形正确做法是“先裁剪后缩放”用drawImage的九参数重载从原帧里抠出目标比例的区域再画到 canvas// 目标尺寸 const TARGET_W 800; const TARGET_H 800; // 原视频帧尺寸 const srcW videoEl.videoWidth; const srcH videoEl.videoHeight; // 按目标比例计算裁剪区域 let cropW srcW; let cropH Math.round(srcW * (TARGET_H / TARGET_W)); if (cropH srcH) { cropH srcH; cropW Math.round(srcH * (TARGET_W / TARGET_H)); } const cropX Math.round((srcW - cropW) / 2); const cropY Math.round((srcH - cropH) / 2); canvas.width TARGET_W; canvas.height TARGET_H; ctx.drawImage(videoEl, cropX, cropY, cropW, cropH, 0, 0, TARGET_W, TARGET_H);另外还有一个经常被业务忽视的点前置摄像头预览默认是镜像的但截图拿到的画面不一定是镜像。大多数手机前置摄像头输出的原始画面在系统层做过处理体现在预览里反而是左右反向。也就是说你在预览里看到的是“镜子里的自己”截帧截出来可能存在方向上的差异。诉求若是“所见即所得”就需要额外画一次镜像翻转诉求是“数据原样”就不用动。我的建议是拍照前把预览和成片的镜像关系用一张写名字的纸在真机上测一遍明确结论后写进需求文档免得验收时扯皮。3.2 用 MediaRecorder 录像MIME 与分片处理录像比截图多一个关键对象MediaRecorder。它的用法是把MediaStream直接交给 recorder浏览器负责编码封装成多媒体文件。let recorder null; let chunks []; function startRecord() { chunks []; const stream videoEl.srcObject; if (!stream) return; const videoTrack stream.getVideoTracks()[0]; const audioTrack stream.getAudioTracks()[0]; // 只有视频轨就能录但想录声音需要先把音频约束打开 recorder new MediaRecorder(stream, { mimeType: pickMimeType() }); recorder.ondataavailable (event) { if (event.data event.data.size 0) { chunks.push(event.data); } }; recorder.onstop () { const blob new Blob(chunks, { type: recorder.mimeType }); const url URL.createObjectURL(blob); // 这里做下载或上传 chunks []; }; recorder.start(1000); // 每 1 秒触发一次 dataavailable避免内存峰值 } function pickMimeType() { const candidates [video/mp4, video/webm;codecsvp9, video/webm;codecsvp8]; return candidates.find((type) MediaRecorder.isTypeSupported(type)) || ; }录像的坑集中在 MIME TYPE 和音频轨两件事上。不同浏览器对封装格式的支持差别很大。Chrome 对video/webm支持好Safari 对video/mp4支持好MediaRecorder.isTypeSupported()存在的意义就是让你在运行环境里动态探测。别写死video/mp4否则 Safari 上可能直接抛NotSupportedError。测过以后你会发现移动端 Safari 的isTypeSupported(video/mp4)通常返回 true而老版本 Android Chrome 对这个可能返回 false所以候选列表的顺序也体现了优先级。如果录制时希望带声音getUserMedia的audio必须设为true。但要注意部分安卓设备在摄像头和麦克风同时工作时会出现音画不同步或者启动变慢的问题。业务对声音没有硬性要求时我建议audio: false省事也省电。recorder.start(1000)里的参数是时间片。传了时间片之后ondataavailable会按这个间隔持续触发避免所有数据都堆到 stop 时一次性写入内存导致页面卡死。不传时间片也能录但录长视频时内存占用不可控。4. 移动端 H5 绕不开的硬骨头HTTPS、权限弹窗与前后摄切换4.1 HTTPS 是硬门槛没有捷径移动端和桌面端的最大区别是用户在手机上打开 H5 页面绝大多数场景走的是 https。但凡是 http 页面iOS 的 Safari 和 Android 的 Chrome 都拿不到摄像头权限。安卓端曾经有一个例外Chrome 允许在 http 下通过 flag 开关绕过这个限制但那是调试期的临时手段线上环境千万别指望。我在某个项目里见过一个“诡异”现象研发用电脑的localhost联调一切正常部署到测试环境后测试同事用手机访问摄像头死活打不开查到最后就是测试环境配的是 http 域名。换成 https 测试域名后问题瞬间消失。如果你在开发期必须用真机联调又没有正式证书最简单的办法是把本地服务通过隧道工具映射成一个公网 https 地址来测。这种临时域名只是调试用不要让它成为习惯因为证书有效期和稳定性都不可控正式上线前必须切回正规 https 域名。4.2 权限被拒后的引导与规避重复弹窗移动端权限弹窗的交互和桌面端不一样。iOS Safari 首次调用getUserMedia会弹系统权限框用户如果点了“不允许”后果比较严重后续再调用同一接口时系统不会重新弹窗而是直接返回NotAllowedError。想恢复只能让用户去系统设置里手动打开相机权限。Android 的 Chrome 行为稍好一些拒绝后再次调用可能还会弹但也不持久。所以我在代码里加了这样一层逻辑捕获到NotAllowedError时不直接提示“权限被拒绝”而是提示一段引导文案告诉用户需要去哪里打开权限。这一步非常影响用户体验尤其是面向非技术用户的 C 端页面。if (err.name NotAllowedError) { showTip(没有相机权限请在浏览器/系统设置中允许使用相机后重试); }还有一个技巧调用之前可以先探测一下navigator.permissions.query({ name: camera })。这个接口在 Chrome 系浏览器可用能提前知道权限状态是granted、denied还是prompt。但 Safari 对它的支持有限所以只能当成增强手段不能当成唯一判断依据。核心原则是不要在用户没点任何按钮时自动弹权限框避免“用户一脸懵就点了拒绝”这种不可逆操作。4.3 前后置摄像头切换的正确思路切换前后摄是高频需求。很多人第一反应是用两次getUserMedia一次给前置一次给后置然后来回换。这个方向没错但实现细节里藏了不少坑。先看错误示范// 错误示范直接又调一次 getUserMedia async function switchToBack() { const stream await navigator.mediaDevices.getUserMedia({ video: { facingMode: environment } }); videoEl.srcObject stream; }这段代码的问题在于切换前没有释放旧轨道。在移动端前一个采集会话还占着摄像头硬件第二次调用会被系统判定为设备占用轻则变慢重则直接NotReadableError。规范操作是先把旧流的轨道全停掉再打开新流。async function switchCamera(facingMode) { // 停掉旧的视频轨道 if (videoEl.srcObject) { videoEl.srcObject.getTracks().forEach((track) track.stop()); videoEl.srcObject null; } const stream await navigator.mediaDevices.getUserMedia({ video: { facingMode, width: { ideal: 1280 }, height: { ideal: 720 } }, audio: false }); videoEl.srcObject stream; await videoEl.play().catch(() {}); }facingMode的局限在于它只能表达“前置/后置”倾向在某些设备上可能都映射到同一个物理摄像头。要精确选某个摄像头可以用deviceId。但deviceId有两个坑一是每次授权前枚举设备拿到的 ID 可能是空字符串授权后才有值二是设备重启或浏览器缓存清除后ID 可能发生变化不能长期保存在后端。我的方案是把enumerateDevices()得到的摄像头列表和用户的选择存到本地缓存下次进来先对比一遍deviceId 还在就继续用不在了就退回facingMode逻辑。切换前后摄还有一个业务细节切换过程中画面会短暂黑屏这是正常现象。如果你不想让用户感知到断流可以在 UI 上先展示一个 loading 遮罩等新流 ready 再揭开。千万不要同时保留两个MediaStream引用那样摄像头会一直处于被占用状态指示灯常亮电池和隐私都很受伤。5. 线上排障复盘五个真实 case 的完整定位链路5.1 case 1手机白屏电脑正常现象同一套代码电脑 Chrome 跑得好好的手机浏览器打开后点击打开摄像头没反应甚至页面白屏。排查思路先看控制台发现navigator.mediaDevices是undefined。电脑正常是因为我用localhost访问的页面算安全上下文手机访问的是http://192.168.x.x属于非安全上下文mediaDevices直接就不存在。验证方式把手机浏览器地址栏改成 https 域名问题消失。这个 case 的教训是用局域网 IP 做真机联调时摄像头能力天然不可用不是代码问题是环境问题。真机调试一定要走 https 隧道或者直接用localhost配合端口转发。5.2 case 2权限给了还是 NotAllowedError现象用户明确点了授权但调用getUserMedia依然返回NotAllowedError。排查思路查错误上下文发现这个 H5 是被嵌入到第三方 App 的 WebView 里外层页面用iframe嵌入而 iframe 标签没有配置权限策略。浏览器安全模型规定iframe 内的页面要使用摄像头外层 iframe 必须显式声明allowcamera。缺了这个声明子页面无论怎么授权都会被拦。验证方式在 iframe 上加上allowcamera; microphone重新加载问题消失。这个 case 提醒我凡是把 H5 的摄像头能力封装成 SDK 塞给第三方 App 的场景都必须把 iframe 的allow属性列入对接文档。很多公司的 WebView 容器框架默认不放权接得多了才发现文档里不写清楚别人根本不知道还有这层限制。5.3 case 3黑屏不出错流也拿到了现象getUserMedia成功video 标签也绑定了srcObjectPromise 全部 resolve但画面一片黑浏览器控制台没有任何报错。排查思路这种“没有错误”的错误最难查。我的做法是分几步验证打印videoEl.videoWidth如果是 0说明视频轨道还没真正输出帧。打印videoTrack.readyState如果是ended说明轨道已经结束了可能是被外部原因中断。检查 video 标签的playsinline属性iOS 上缺了它会进入全屏播放模式页面内显示区域是黑的。检查是否调用了videoEl.play()。有些浏览器 autoplay 策略严格视频不调用 play 就不会真正渲染画面。验证方式补充playsinline并在绑定 srcObject 后手动调用play()。多数场景到这里画面就出来了。还有一类黑屏是摄像头被系统相机占用了表现在轨道状态异常或黑屏但音频正常。遇到这种情况提示用户关掉其他占用摄像头的应用再回来重试。5.4 case 4页面卡顿掉帧摄像头被降级现象打开摄像头后页面整体变卡视频画面只有十几帧CPU 占用率飙高手机发烫。排查思路最直接的原因是采集参数没有限流。默认情况下浏览器会尽可能选高分高帧率比如 4K 60fps。手机摄像头采集能力很强但网页解码、Canvas 绘制、视频渲染全靠 CPU/GPU能力跟不上就直接掉帧。我用getSettings()打印后发现某个设备实际协商出来的参数是 3840x2160 60fps而这只是用来做一个头像框预览。验证方式把 constraints 改成video: { width: { ideal: 1280, max: 1280 }, height: { ideal: 720, max: 720 }, frameRate: { ideal: 30, max: 30 }, facingMode: user }之后页面流畅度明显提升。后续做性能调优时我还会把videoWidth大于 1280 时用 Canvas 二次缩放进一步降低下游处理压力。5.5 case 5离开页面摄像头指示灯还亮现象用户从业务页面跳走或者关闭弹窗后手机顶部状态栏的摄像头指示灯依然亮着隐私敏感场景下这是会出事故的。排查思路代码里只做了“打开摄像头”没有做“关闭摄像头”。getUserMedia返回的MediaStream本身有一个生命周期但它不会因为页面跳转而自动释放尤其在单页应用里路由切换后旧组件实例仍然持有 stream 引用采集会话就一直在。摸过一遍源码后发现停止采集最可靠的方式是显式调用MediaStreamTrack.stop()function releaseCamera() { if (videoEl.srcObject) { videoEl.srcObject.getTracks().forEach((track) track.stop()); videoEl.srcObject null; } }验证方式调用releaseCamera()之后指示灯熄灭。此后的约定是组件卸载、路由切换、弹窗关闭这三个时机必须统一走释放方法谁也不许单独写“只清 UI 不停流”的代码。6. 容易被忽略的体验细节释放、压缩、降级的实战建议6.1 制定一套“摄像头资源生命周期”规范摄像头是独占型硬件资源不是你页面想用就用、想扔就扔的东西。我现在的习惯是任何接入getUserMedia的页面都必须遵守三条铁律第一打开和关闭必须成对出现。页面有“打开摄像头”按钮就必须有等价的“关闭摄像头”逻辑不管是按钮、路由切换、弹窗关闭还是组件销毁。第二页面不可见时主动释放。移动端用户切到后台再接电话再切回来摄像头如果一直被占着不仅耗电还可能被系统回收导致黑屏。可以监听visibilitychange事件页面变为 hidden 时停流变为 visible 时按需重开。第三异常路径也要释放。getUserMedia成功后代码发生了别的错误比如人脸检测初始化失败这时候没人会记得去停流。推荐写一个统一的状态管理对象把“当前流”挂在上面任何出口都调同一个release()方法。6.2 自拍镜像的显示与数据偏差前置摄像头预览默认是镜像的这是为了让用户看到自己时符合照镜子的直觉。但如果你把视频流直接传给后端做动作识别、人脸比对算法那边拿到的是原始画面和预览可能是左右翻转的比对结果会出大问题。这里没有绝对正确的答案取决于产品定义面向用户的预览要镜像面向算法的数据要保持原生方向。我的建议是两条线分开预览层用 CSStransform: scaleX(-1)做镜像让用户看着舒服采集/上传层永远传原始轨道画面让算法处理正规数据。千万不要为了“所见即所得”把轨道里的画面真的翻转了宁可让算法侧来做翻转别动采集源。6.3 降级方案与移动端真机测试建议摄像头能力再强也扛不住用户的浏览器版本太老、权限被系统恶意软件禁用、企业 WebView 容器把getUserMedia整个阉割掉。这时候页面不能干瞪眼得给一条降级路径至少提供一个“从相册选择照片上传”的入口让业务在极端情况下仍能走通。我每次做这类功能都会准备一个最小的真机测试矩阵iOS Safari、Android Chrome、微信内置 WebView、目标行业常见的定制 WebView。尤其是 Android 厂商的 WebView 差异非常大同一个页面在 Chrome 里跑得好在某个品牌自带浏览器里可能连mediaDevices都拿不到。笔者的经验是不要只测 Chrome至少把主流 WebView 过一遍权限引导文案和错误提示都要做成 H5 页面内置的 UI别依赖任何系统的默认弹窗文案。最后再说一个我在几个项目里反复验证过的体会把 constraints 写给“合理且宽泛”是最稳妥的。给理想值而不是精确值给上限而不是硬约束剩下交给浏览器去协商。这听起来不酷但在碎片化的安卓世界里这种写法存活率最高。做 H5 摄像头功能本质上是在和浏览器安全模型、系统权限机制、硬件设备差异三座大山打交道少一环节的敬畏线上就会多一个黑屏工单。