1. 先搞清楚 mediaDevices 是干什么的以及它为何会不存在1.1 它是浏览器媒体能力的总入口先把这个 API 的身世说清楚。navigator.mediaDevices是挂载在navigator对象上的一个单例属性它的类型是MediaDevices可以理解成浏览器对外提供的多媒体设备总入口。你在网页里做的几乎所有跟音视频硬件打交道的事都要经过它getUserMedia()获取摄像头和麦克风也就是视频通话、拍照、录音的核心方法。getDisplayMedia()采集屏幕画面做屏幕共享、录屏时靠它。enumerateDevices()枚举当前设备列表能拿到摄像头、麦克风、扬声器的 label 和设备 ID。ondevicechange事件用户拔插摄像头、切换默认麦克风时触发。所以当你调用navigator.mediaDevices.getUserMedia()时如果控制台报navigator.mediaDevices返回 undefined说明你连这扇门都没找到后面所有操作全部免谈。很多人第一反应是去改代码、加 polyfill、换调用方式结果折腾半天还是 undefined。原因很简单大多数情况下代码一点问题没有问题出在页面运行环境上。1.2 核心真相这不是 BUG而是浏览器的安全策略我先把最关键的一句话放在这里navigator.mediaDevices只在安全上下文Secure Context中才会暴露给网页。非安全上下文里的页面浏览器会在实现层面直接把整个属性隐藏掉你访问到的就是 undefined。这个安全上下文不是后端工程师口中的 session 或 token而是 W3C 制定的一个浏览器安全模型概念。简单说一个页面只有在满足以下条件之一时才算是安全上下文通过https://或wss://协议访问。访问http://localhost、http://127.0.0.1、http://[::1]等本机回环地址。通过file://协议打开本地文件各浏览器实现差异较大别完全指望它。浏览器扩展页、部分系统自带页面等特殊来源。也就是说如果你直接在浏览器地址栏输入http://192.168.1.10:8080或者随便一个http://开头的测试地址然后在这个页面里跑navigator.mediaDevices得到的结果几乎必然就是undefined。这不是你的代码有 bug而是浏览器故意不给你。这里面的设计逻辑其实很朴素。getUserMedia拿到的是用户的实时摄像头画面和麦克风声音如果这种能力暴露给任意 HTTP 网站那恶意页面就可以在用户毫无感知的情况下偷拍偷录。所以浏览器选择了一种非常强硬的手段不是等调用时才拒绝那样用户会看到报错、可能会起疑心而是直接在对象的属性层面把 API 抹掉。你连访问都访问不到自然谈不上调用。用 W3C 标准的说法MediaDevices接口在 WebIDL 定义里标了[SecureContext]标记有这个标记的属性在非安全上下文里就会从接口定义中直接消失。1.3 兼容性时间线另外浏览器兼容性也是一个需要知道的维度。虽然navigator.mediaDevices现在已经是所有现代浏览器的标准能力但它是逐步普及的浏览器支持mediaDevices的大致版本备注Chrome47同时要求安全上下文Firefox55早期版本在 HTTP 下可通过配置放开Safari11仅 HTTPS且对用户手势要求严格Edge15基于 Chromium 之前的旧 EdgeIE全部不支持需要降级方案或直接放弃Android WebView随系统版本而定老版本 WebView 大概率缺失如果你的目标用户还有比较老的环境那么只判断navigator.mediaDevices是否存在还不够还需要考虑navigator.getUserMedia这类带前缀的旧写法。这个我在后面的兼容代码里会给完整方案。2. 两条系统排查链路先看环境再看代码2.1 环境自检五步法碰见navigator.mediaDevices返回 undefined我的习惯是先别动代码直接在控制台里做一轮环境自检。你按这个顺序走一遍99% 的根因都能定位到。第一步确认页面协议。在控制台输入location.protocol看看返回的是什么。如果是http:那基本不用往下查了这就是根因。如果是https:再继续往下走。顺便看一眼location.hostname确认是不是localhost因为有些人在公司内网环境虽然 URL 看起来是http://192.168.x.x但 IP 并不算安全上下文。第二步确认页面是不是被嵌在 iframe 里。输入window.self ! window.top返回true说明当前页面在一个 iframe 中。iframe 里的媒体权限受父页面权限策略约束后面有专门一节讲这个坑。第三步确认浏览器版本。输入下面这行命令可以在控制台里快速打印出浏览器是否支持mediaDevices以及支持到什么程度const md navigator.mediaDevices; const legacy navigator.getUserMedia || navigator.webkitGetUserMedia; console.table({ hasMediaDevices: !!md, hasGetUserMedia: !!(md md.getUserMedia), hasLegacyGetUserMedia: !!legacy, protocol: location.protocol, inIframe: window.self ! window.top });第四步排除浏览器设置和扩展干扰。Chrome 里可以在地址栏输入chrome://settings/content/camera查看摄像头权限是否被全局禁止。如果设置了网站可以请求使用摄像头但某个站点单独被设为禁止也会出现调用时直接被拒的情况。不过说实话权限设置影响的是调用结果通常不会让mediaDevices属性本身变成 undefined但为了排查彻底还是值得看一眼。第五步区分是属性不存在还是方法不存在。如果navigator.mediaDevices是一个对象但navigator.mediaDevices.getUserMedia是 undefined那是另一码事通常是浏览器太老或者实现不完整。这个区分很重要因为后续处理方式完全不同。2.2 代码层面常见的人为制造 undefined环境检查没问题之后再回头看代码。这个报错很多时候是环境问题但代码里也有几个非常隐蔽的坑我列一下我实际见过的第一个坑变量名遮蔽。有人为了写起来方便在某个作用域里定义了const navigator ...之类的局部变量导致访问到的navigator根本不是全局对象。更常见的是在某个函数里把navigator作为参数名传了进去。这种问题排查起来很蛋疼因为控制台里直接敲navigator.mediaDevices是好的但代码里跑起来就是 undefined。建议遇到诡异情况时在navigator.mediaDevices之前加一层window.navigator.mediaDevices试试强制走全局。第二个坑SSR 环境下误用navigator。在 Node.js 环境、服务端渲染比如 Next.js 的 getServerSideProps里压根没有navigator这个对象。这时候访问navigator.mediaDevices报的其实不是 undefined而是 navigator is not defined。但很多新手会把这两者混淆所以一旦看到跟navigator相关的错误先确认代码是在浏览器端执行的不要在服务端裸访问。第三个坑拼写错误。mediaDevices是mediaDevices多了个复数。写成mediaDevice、mediaDevieces、MediaDevices大写开头都是拿不到值的。还有人在 TypeScript 项目里把类型名MediaDevices和实例属性navigator.mediaDevices搞混虽然编译能过但运行时不存在的属性就是 undefined。第四个坑某些 polyfill 或公共代码在某处主动做了一层拦截。有些团队为了兼容会在全局覆盖navigator.mediaDevices或者借助 Proxy 做拦截如果拦截逻辑写得不严谨就可能让属性在特定条件下为 undefined。遇到这种情况在控制台里执行Object.getOwnPropertyDescriptor(Object.getPrototypeOf(navigator), mediaDevices)能看到属性描述符到底长什么样如果出现自定义的 getter那基本就是被改过了。3. 从空白页到真正拿到摄像头安全上下文与兼容写法的落地3.1 开发环境的三种可复现方案如果你确认问题出在 HTTP 环境那就别想着通过改代码绕过去了——绕不过去。浏览器这个安全策略没有后门只能把页面弄到安全上下文里。我实际在开发中用这三种方式方式一直接用 localhost。这是最简单省事的方式。Chrome、Firefox 对http://localhost和http://127.0.0.1都视为安全上下文所以本地开发时只要通过localhost访问页面navigator.mediaDevices就不会是 undefined。注意别用局域网 IP 访问本地服务http://192.168.x.x:8080不算安全上下文。方式二用 mkcert 生成本地可信任的 HTTPS 证书。本地开发如果必须用 IP 或者自定义域名访问比如调试移动端手机要连开发机的 IP就需要上 HTTPS。mkcert 是这类工具里最简单的一个一条命令生成证书把 CA 安装到系统信任列表里之后本地 Nginx 或 dev server 配上证书就能以 HTTPS 访问浏览器会认。安装和生成大概是这样# 安装 mkcertmacOS 用 brewWindows 用 chocolatey 或官方包 brew install mkcert mkcert -install mkcert 192.168.1.10 localhost生成的192.168.1.10localhost.pem和-key.pem就是证书和私钥配到你的 Web 服务器里即可。这样手机用https://192.168.1.10:8443访问时浏览器就不再把它当作不安全环境。方式三反向代理一层 HTTPS。如果你的页面本身跑在 HTTP 端口不想动业务代码可以在前面加一层 Nginx 或者 Caddy由代理完成 HTTPS 终结。比如用 Caddy两行配置就能搞定Caddy 会自动申请和续签证书需要有公网域名。如果是纯内网环境申请不了公网证书还是用 mkcert 这条路更稳。3.2 兼容旧浏览器的 getUserMedia 降级写法环境就绪之后代码层面也不能只是写现代标准写法。我给项目里最常用的一个兼容封装直接抄走就行function getSafeMediaDevices() { return navigator.mediaDevices || {}; } function getGetUserMedia() { const md getSafeMediaDevices(); if (md typeof md.getUserMedia function) { return md.getUserMedia.bind(md); } const legacy navigator.getUserMedia || navigator.webkitGetUserMedia || navigator.mozGetUserMedia || navigator.msGetUserMedia; if (legacy) { return legacy.bind(navigator); } return null; } function getMediaStream(constraints) { const getUserMedia getGetUserMedia(); if (!getUserMedia) { return Promise.reject(new Error(当前浏览器不支持 getUserMedia)); } return Promise.resolve(getUserMedia(constraints)); }这个封装的逻辑很简单优先用标准的navigator.mediaDevices.getUserMedia没有就降级到navigator.getUserMedia以及各浏览器的前缀版本。这里有个很容易被忽略的细节legacy版本的getUserMedia调用时this必须指向navigator所以封装里用了bind(navigator)。有人直接把navigator.getUserMedia取出来赋值给一个变量再调用结果报各种类型错误就是丢了this。3.3 从拿到流到上屏一个最小可运行示例拿到MediaStream之后很多人的下一步是塞进video标签。这里也有一个常见的认知偏差早期很多人用video.src URL.createObjectURL(stream)这种写法新标准已经推荐直接用video.srcObject stream。srcObject直接接受MediaStream对象不需要创建 Blob URL也更不容易内存泄漏。最小示例大概是这样的!DOCTYPE html html langzh-CN head meta charsetUTF-8 title摄像头调试页/title /head body video idcamera autoplay playsinline muted stylewidth: 480px/video script async function startCamera() { try { const stream await getMediaStream({ video: { width: 1280, height: 720 }, audio: false }); const video document.getElementById(camera); video.srcObject stream; } catch (err) { console.error(摄像头启动失败, err); } } startCamera(); /script /body /html这里几个属性值得解释一下。autoplay表示流准备好后自动播放playsinline对 iOS 尤其重要不加的话在 iPhone 上容易全屏播放或者黑屏muted则避免摄像头画面里的回声和啸叫。我用的是宽高约束而不是简单的video: true因为很多摄像头默认的分辨率很小画质感人明确声明想要的宽高能唤起更好的设备配置。3.4 错误处理这些异常情况要提前写好getUserMedia的报错信息对新手非常不友好一堆英文错误名关键是要对应到实际场景。我踩过的坑都在这张表里了错误名称实际含义最常见的触发场景NotAllowedError用户拒绝了权限请求用户点了不允许或 iframe 权限策略阻止NotFoundError找不到符合约束条件的设备台式机没插摄像头或设备已被拔出NotReadableError设备不可读摄像头被其他程序如 Zoom、OBS独占OverconstrainedError约束与设备能力不匹配请求 4K 但摄像头只支持 720PTypeError参数类型错误constraints是空对象或包含不支持的类型AbortError用户未出现就跳过了权限提示常见的用户侧误操作或系统层面干预实际项目里我通常会在catch里判断err.name并给出对应的中文提示。相比出错了三个字用户看到摄像头被其他程序占用请关闭占用程序后重试会更愿意配合。这个细节在面向非技术用户的产品里尤其重要。4. 那些非标准环境的真相about:config、扩展插件与本地调试4.1 about:config 为什么救不了你这个点我必须单独拿出来说因为坊间流传的解决 navigator.mediaDevices 返回 undefined的办法里最坑的就是让人去浏览器地址栏输入about:config。这个方法不仅在技术上无效连使用场景都对不上。about:config是 Firefox 的配置编辑器类似 Chrome 的chrome://flags里面有大量浏览器底层偏好设置。在 Firefox 比较老的版本里确实可以通过修改media.navigator.enabled之类的配置项让 HTTP 页面也能调用部分媒体能力。但问题在于第一你现在打开的大概率是 Chrome 或 Edge地址栏输入about:config根本打不开那个页面浏览器会直接搜索这个关键词把你带到搜索结果页去。第二即便是 Firefox现代版本出于安全考虑也已经大幅收紧了这类非标准开关靠改配置让 HTTP 页面使用navigator.mediaDevices的做法基本失效了。第三也是最重要的一点about:config改的是浏览器层面的偏好设置而你真正需要的是让你的页面处于安全上下文中。这两个层级完全不一样。你可以把浏览器配置理解成大楼的物业规定而安全上下文是楼层消防门——物业规定改得再全消防门不开就是不开。所以以后再看到这类回答直接跳过就行。它一开始就是把方向带偏了。4.2 扩展页面与特权上下文的例外说到浏览器扩展这里确实有一个特例很多做开发的人会拿它来当调试捷径。Chrome 扩展页面运行在chrome-extension://协议下这个来源被浏览器视为可信来源所以扩展的 background、popup 页面里navigator.mediaDevices是正常暴露的不需要 HTTPS。这意味着什么意味着如果你本地只是临时想验证一下摄像头能不能正常工作不必急着搭 HTTPS可以做一个极简的 Chrome 扩展把摄像头调试页面塞进 popup 里。一个最小可用的扩展只需要三个文件// manifest.json { manifest_version: 3, name: Camera Debug Tool, version: 1.0.0, action: { default_popup: popup.html }, permissions: [videoCapture] }!-- popup.html -- !DOCTYPE html html body video idcam autoplay playsinline muted stylewidth: 320px/video button idstart开始/button script srcpopup.js/script /body /html// popup.js document.getElementById(start).addEventListener(click, async () { const stream await navigator.mediaDevices.getUserMedia({ video: true }); document.getElementById(cam).srcObject stream; });把这三个文件放进一个目录Chrome 的扩展管理页开启开发者模式选择加载已解压的扩展程序选中这个目录即可。然后点工具栏上的扩展图标popup 就是一个可以直接使用摄像头的调试页面。要注意的是manifest 里的permissions: [videoCapture]不是可选项。如果漏了扩展页面调用getUserMedia也会被拦。另外扩展的 content script 不能等同对待content script 虽然由扩展注入但它运行在普通网页的上下文里仍然要遵守目标页面的安全上下文限制。换句话说扩展自己写的页面有特权但扩展到别人网页里跑的脚本没有特权。这个技巧平时最多用来快速排查摄像头硬件是否被占用这类问题。真正做产品功能时别想着拿扩展特权去绕 HTTPS那只是给自己埋雷。4.3 本机调试的正路仍然只有一个安全上下文话说回来如果你是在正经开发一个网页应用而不是做浏览器扩展本机调试的正路就是让页面跑在安全上下文里没有别的捷径。你可能会想Chrome 有没有什么启动参数能强制放行--unsafely-treat-insecure-origin-as-secure确实存在它可以指定某个 HTTP 源被当作安全上下文处理。比如chrome --unsafely-treat-insecure-origin-as-securehttp://192.168.1.10:8080 --user-data-dir/tmp/temp-profile每次启动 Chrome 都得带这一长串参数而且还要用独立的--user-data-dir不然不生效。日常调试这么搞实在太折腾了我是用了几次就放弃了。对比下来mkcert 加 HTTPS 一劳永逸工作流顺畅得多。5. 三个经常被忽略的隐蔽场景iframe、SSR与Service Worker5.1 iframe 的权限策略Permissions Policy前面环境自检时提到过 iframe这里展开细说因为这个坑非常隐蔽。假设你的页面在https://yourdomain.com一切正常navigator.mediaDevices存在调用也能弹出权限框。但你把这个页面嵌到另一个网站的 iframe 里比如iframe srchttps://yourdomain.com/camera然后发现getUserMedia直接报权限错误甚至在某些浏览器里navigator.mediaDevices变成了 undefined。原因在于 iframe 的内容默认受父页面的权限策略Permissions Policy约束。摄像头和麦克风属于默认拒绝的能力除非 iframe 标签上显式声明允许。正确的写法是这样iframe srchttps://yourdomain.com/camera allowcamera; microphone frameborder0 /iframe注意这里的allow属性不是给人看的提示文案而是机器读取的权限声明。如果你漏掉了子页面就像在一间没有窗户的房间里试图往外看无论子页面自己的安全上下文多正统都拿不到媒体能力。还有一种情况是父页面通过响应头Permissions-Policy: camera(self)限制了只有自己能用摄像头那嵌入的 iframe 怎么声明都不管用需要父页面配合放开。排查这类问题时我一般会在 iframe 内的页面控制台执行navigator.mediaDevices navigator.mediaDevices.getUserMedia再对比父页面里同样的调用很快就能定位是不是权限策略的问题。5.2 SSR/服务端渲染环境服务端渲染的坑和 iframe 是两个方向。iframes 是页面有环境但被策略限制SSR 是压根没有浏览器环境。很多用 Next.js、Nuxt 或者自定义 SSR 框架的开发者习惯在组件初始化的时候访问navigator结果发现服务端渲染阶段直接报错navigator is not defined严格来说这个报错和标题的mediaDevices还不是同一个错但从排查思路上说它们经常一起出现。比较稳妥的写法是给检测函数加一层环境守卫function isBrowser() { return typeof window ! undefined typeof navigator ! undefined; } function supportsMediaDevices() { if (!isBrowser()) return false; return typeof navigator.mediaDevices ! undefined typeof navigator.mediaDevices.getUserMedia function; }这样在服务端渲染时supportsMediaDevices()返回false代码不会炸在浏览器端则能准确判断是否支持。不要图省事直接写if (navigator.mediaDevices)在没有navigator的环境里这一行就是定时炸弹。数据请求、组件挂载这些逻辑记得只在useEffect/onMounted这类客户端生命周期里做。5.3 Service Worker 里是拿不到摄像头的Service Worker 是另一个容易让人困惑的地方。它虽然运行在浏览器里但运行环境和普通页面完全不同——没有 DOM没有window当然也没有媒体设备访问能力。你在 Service Worker 里访问navigator.mediaDevices结果就是 undefined。我见过有人试图在 Service Worker 里做录音推流想靠 Service Worker 常驻后台实现后台录音这是方案选型错了。Service Worker 的定位是拦截请求、管理缓存、处理推送通知它不是用来跑音视频采集逻辑的。正确的架构是采集逻辑放在页面里页面拿到了流之后用 WebRTC 或 WebSocket 把流送出去需要缓存或离线能力时再让 Service Worker 参与网络的拦截和资源的缓存。不要在 Service Worker 里试图调用任何跟 DOM 或媒体硬件相关的 API这条路从一开始就不通。6. 兜底封装与上线前的自检清单6.1 一个日常可用的工具函数把前面所有要点整合成一个可以直接放入项目公共方法库的检测函数这是我目前在项目里用的一套涵盖环境守卫、兼容降级、错误信息归一化async function requestCamera(constraints { video: true, audio: false }) { const errors { NotAllowedError: 用户拒绝了摄像头权限请求, NotFoundError: 未检测到可用的摄像头设备, NotReadableError: 摄像头被其他程序占用请关闭占用程序后重试, OverconstrainedError: 当前设备不满足所要求的摄像头规格, TypeError: 摄像头请求参数格式错误, AbortError: 权限请求被中断请重试 }; if (typeof navigator undefined) { throw new Error(当前环境不是浏览器无法访问摄像头); } const mediaDevices navigator.mediaDevices || {}; let getUserMedia mediaDevices.getUserMedia; if (!getUserMedia) { const legacy navigator.getUserMedia || navigator.webkitGetUserMedia || navigator.mozGetUserMedia || navigator.msGetUserMedia; if (legacy) { getUserMedia legacy.bind(navigator); } } if (!getUserMedia) { throw new Error(当前浏览器不支持访问摄像头请升级浏览器或使用 HTTPS 访问); } try { return await getUserMedia(constraints); } catch (err) { const msg errors[err.name] || 摄像头启动失败${err.message || err}; throw new Error(msg); } }使用方式很简单const stream await requestCamera({ video: { width: 1280 }, audio: true });。这个函数的好处是把环境判断、旧浏览器降级、错误提示都收敛在一个地方业务层只需要关心拿到流之后的渲染逻辑不用到处散落着navigator.mediaDevices的判断。6.2 上线前的检查清单我自己每次做带摄像头功能的功能上线前都会过一遍这个清单你可以直接复制到项目的提交检查项里线上页面确认是 HTTPS不能用 HTTP。这是navigator.mediaDevices存在的第一前提。如果页面会被其他站点以 iframe 方式嵌入确认 iframe 标签上加了allowcamera; microphone。如果页面本身嵌入了含媒体能力的第三方 iframe确认自己的响应头没有用Permissions-Policy把camera和microphone全部锁死。调用getUserMedia的时机必须在用户手势之后click/tap 事件回调里。Safari 对这个要求尤其严格不是用户主动触发的调用会直接拒绝。iOS 原生壳WKWebView内嵌页面时确认原生工程配置了NSCameraUsageDescription和NSMicrophoneUsageDescription否则调用会闪退。摄像头可能被其他程序占用代码里的错误提示要提前写好别等到用户反馈了才补。页面加载时不要自动调用getUserMedia先留一个按钮让用户主动点击触发。用户体验上更友好也能避开浏览器的自动播放策略。6.3 如果还没解决还能往哪里查极少情况下环境、代码都排查完了还是有问题这时候就要借助浏览器内部的诊断工具了。Chrome 地址栏输入chrome://media-internals可以打开媒体内部状态页面这里能看到当前所有媒体流的状态、有没有报错、设备有无在运行。另一个是 Chrome DevTools 的 Security 面板它能直接告诉你当前页面的安全上下文状态——如果显示 Insecure origin那mediaDevices为 undefined 就太正常了。还有一招是先用其他网页测试摄像头硬件本身是否正常比如打开一个视频通话网页或者任何一个调用摄像头能力正常的页面看一眼。如果别的页面能正常出画面硬件没问题问题在你的页面环境或代码。如果别的页面也黑屏或报错先处理设备驱动、系统权限再回头查代码也不迟。我个人的经验是花五分钟跑完环境自检五步法90% 的navigator.mediaDevicesundefined 问题都能当场定位。剩下 10% 才需要动用这些深层次工具。所以下次再看到这个报错第一件事是开控制台看location.protocol而不是急着改代码——这个习惯帮我省了太多时间。
