企业官网建设流程全解析

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现在已经是所有现代浏览器的标准能力，但它是逐步普及的：

如果你的目标用户还有比较老的环境，那么只判断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是media+Devices，多了个复数。写成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 访问，浏览器会认。

安装和生成大概是这样：

# 安装 mkcert（macOS 用 brew，Windows 用 chocolatey 或官方包） brew install mkcert mkcert -install mkcert 192.168.1.10 localhost

生成的192.168.1.10+localhost.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 lang="zh-CN"> <head> <meta charset="UTF-8"> <title>摄像头调试页</title> </head> <body> <video id="camera" autoplay playsinline muted style="width: 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的报错信息对新手非常不友好，一堆英文错误名，关键是要对应到实际场景。我踩过的坑都在这张表里了：

实际项目里，我通常会在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 id="cam" autoplay playsinline muted style="width: 320px"></video> <button id="start">开始</button> <script src="popup.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-secure="http://192.168.1.10:8080" --user-data-dir=/tmp/temp-profile

每次启动 Chrome 都得带这一长串参数，而且还要用独立的--user-data-dir，不然不生效。日常调试这么搞实在太折腾了，我是用了几次就放弃了。对比下来，mkcert 加 HTTPS 一劳永逸，工作流顺畅得多。

5. 三个经常被忽略的隐蔽场景：iframe、SSR与Service Worker

5.1 iframe 的权限策略（Permissions Policy）

前面环境自检时提到过 iframe，这里展开细说，因为这个坑非常隐蔽。假设你的页面在https://yourdomain.com，一切正常，navigator.mediaDevices存在，调用也能弹出权限框。但你把这个页面嵌到另一个网站的 iframe 里，比如<iframe src="https://yourdomain.com/camera">，然后发现getUserMedia直接报权限错误，甚至在某些浏览器里navigator.mediaDevices变成了 undefined。

原因在于 iframe 的内容默认受父页面的权限策略（Permissions Policy）约束。摄像头和麦克风属于"默认拒绝"的能力，除非 iframe 标签上显式声明允许。正确的写法是这样：

<iframe src="https://yourdomain.com/camera" allow="camera; microphone" frameborder="0"> </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 上线前的检查清单

我自己每次做带摄像头功能的功能上线前，都会过一遍这个清单，你可以直接复制到项目的提交检查项里：

1. 线上页面确认是 HTTPS，不能用 HTTP。这是navigator.mediaDevices存在的第一前提。
2. 如果页面会被其他站点以 iframe 方式嵌入，确认 iframe 标签上加了allow="camera; microphone"。
3. 如果页面本身嵌入了含媒体能力的第三方 iframe，确认自己的响应头没有用Permissions-Policy把camera和microphone全部锁死。
4. 调用getUserMedia的时机必须在用户手势之后（click/tap 事件回调里）。Safari 对这个要求尤其严格，不是用户主动触发的调用会直接拒绝。
5. iOS 原生壳（WKWebView）内嵌页面时，确认原生工程配置了NSCameraUsageDescription和NSMicrophoneUsageDescription，否则调用会闪退。
6. 摄像头可能被其他程序占用，代码里的错误提示要提前写好，别等到用户反馈了才补。
7. 页面加载时不要自动调用getUserMedia，先留一个按钮让用户主动点击触发。用户体验上更友好，也能避开浏览器的自动播放策略。

6.3 如果还没解决，还能往哪里查

极少情况下，环境、代码都排查完了还是有问题，这时候就要借助浏览器内部的诊断工具了。

Chrome 地址栏输入chrome://media-internals，可以打开媒体内部状态页面，这里能看到当前所有媒体流的状态、有没有报错、设备有无在运行。另一个是 Chrome DevTools 的 Security 面板，它能直接告诉你当前页面的安全上下文状态——如果显示 "Insecure origin"，那mediaDevices为 undefined 就太正常了。

还有一招是先用其他网页测试摄像头硬件本身是否正常，比如打开一个视频通话网页或者任何一个调用摄像头能力正常的页面看一眼。如果别的页面能正常出画面，硬件没问题，问题在你的页面环境或代码。如果别的页面也黑屏或报错，先处理设备驱动、系统权限，再回头查代码也不迟。

我个人的经验是，花五分钟跑完环境自检五步法，90% 的navigator.mediaDevicesundefined 问题都能当场定位。剩下 10% 才需要动用这些深层次工具。所以下次再看到这个报错，第一件事是开控制台看location.protocol，而不是急着改代码——这个习惯帮我省了太多时间。