平时在做项目演示、客户端联调或远程教学时经常需要把浏览器页面、桌面窗口甚至整个屏幕投到另一个屏幕上。传统的做法是装第三方投屏软件要么收费要么有广告要么在局域网里识别不到设备折腾一圈下来比写业务代码还累。后来调研了一圈发现直接基于浏览器本身就能实现跨设备投屏而且核心能力全部来自浏览器原生 API再配合一个开源扩展外壳就能在 Chrome、Edge 甚至 Safari 中使用同一套投屏逻辑。这篇文章就把这套方案的原理、代码和踩坑记录完整拆解出来方便有类似需求的同学直接复用。本文适合以下几类读者想把浏览器内容投到另一台电脑、电视或投影设备的开发者。负责团队内部会议、教学演示、直播推流工具选型/开发的技术同学。想了解getDisplayMedia、WebRTC、信令服务、浏览器扩展开发的进阶学习者。读完本文后你将掌握浏览器投屏的完整架构和核心原理。Chrome、Edge、Safari 下投屏能力的使用差异。一个最小可运行的投屏 demo 的源码实现。常见报错和坑点的排查方法。生产环境落地时的工程建议。下面我们直接进入正题。1. 浏览器投屏到底是什么解决什么问题1.1 浏览器投屏的定义浏览器投屏指的是以浏览器作为投屏发起端或接收端把浏览器标签页、窗口或整个桌面屏幕的内容通过 WebRTC、WebSocket 等技术传输到另一台设备的浏览器中进行播放和展示。它和手机投电视的场景类似但不需要专门的投屏协议芯片也不需要安装额外的视频播放客户端。只要发起端和接收端的设备都有现代浏览器就能完成整个投屏链路。典型流程可以简化为发起端浏览器采集屏幕画面。通过 WebRTC 建立点对点媒体通道。接收端浏览器解码并播放画面。两端之间通过信令服务协调连接参数。这种方式最大的亮点在于所有媒体采集、编码、传输、解码和播放能力都是浏览器自带的能力开发者不用关心复杂的音视频编码细节也不用购买第三方投屏 SDK。1.2 它能解决什么问题传统投屏方案的痛点很明显系统级投屏如 Miracast、AirPlay、DLNA虽然方便但对设备和系统版本有严格限制。Windows 电脑和 iPhone 之间、安卓手机和 Mac 之间经常互相不兼容。第三方投屏软件需要两端都安装客户端还要注册账号、联网鉴权使用门槛高。会议室专用投屏盒子成本高不适合临时场景。投屏时经常被软件广告弹窗干扰体验不好。而浏览器投屏只需要一个浏览器页面或浏览器扩展就能在局域网内完成投屏。尤其适合以下场景使用场景传统方案浏览器投屏方案技术会议分享代码需要投屏硬件或软件打开接收端网页即可远程联调演示使用视频会议软件通过 WebRTC 自建低延迟通道直播录屏推流需要 OBS 等客户端浏览器直接采集并传输产品 Demo 演示需要特定投屏协议支持 Chrome、Edge、Safari 的通用方案1.3 为什么开发者需要掌握浏览器投屏背后并不是什么黑科技而是 Google、Apple、Microsoft 等浏览器厂商共同推进的 Web 标准能力组合。掌握这套能力不仅能用现成开源插件快速实现投屏还能根据业务需求定制开发把投屏能力集成到自己的网页管理后台中。在会议系统、在线教育、远程协助产品中加入浏览器分享能力。改造现有直播推流工具减少客户端安装依赖。从就业和项目角度来说getDisplayMedia WebRTC 已经是音视频和前端领域的核心技能组合学习价值很高。2. 技术方案选型为什么推荐浏览器扩展方案2.1 主流投屏方案对比我整理了一张对比表方便理解不同方案的适用边界对比维度系统级投屏第三方投屏软件浏览器扩展投屏安装成本系统自带无需安装两端都要安装客户端只需要安装一个扩展或打开网页跨平台能力受品牌和系统限制一般支持主流平台只要浏览器支持 WebRTC 即可延迟表现较好取决于软件实现局域网内通常 100~300 毫秒自定义能力低较低高可完全自定义稳定性受系统和驱动影响依赖服务商依赖浏览器和网络环境成本无需额外成本高级功能常收费开源方案免费可自建从表格可以看出浏览器扩展方案的灵活性是最好的。尤其是在企业内部已有 Web 技术栈的情况下用一套网页代码就能同时覆盖多种设备。2.2 浏览器扩展方案的优势具体来说选择浏览器扩展做投屏有以下几点优势第一安装门槛低。Chrome 和 Edge 都支持开发者模式加载扩展也可以发布到官方商店。用户不需要理解复杂的网络协议点一下扩展图标就能进入发送端页面。第二能力接近原生应用。通过getDisplayMediaAPI扩展可以直接采集屏幕画面通过tabCapture或desktopCapturerElectron 场景还能做更多细粒度的标签页采集。第三代码可复用。扩展内部本质上是 HTML、CSS 和 JavaScript和普通网页技术栈完全一致。你把投屏逻辑写成一个网页再通过扩展包装一层就能获得浏览器级的权限和入口。第四开源生态成熟。开源社区里已经有多个基于 WebRTC 的浏览器投屏项目思路和结构都比较成熟可以直接参考。2.3 方案需要注意的边界浏览器投屏并不是万能的有几个边界需要提前了解Safari 不支持直接安装 Chrome/Edge 的 crx 扩展。但 Safari 支持 Web Extension 的转换机制也支持getDisplayMedia屏幕共享 API因此投屏页面在 Safari 中是可用的只是扩展形态需要单独适配。WebRTC 在公网环境下依赖 STUN/TURN 服务器。如果只是局域网投屏可以不用配置跨网络投屏时必须部署至少一个 TURN 服务器用于 NAT 穿透和媒体转发。浏览器页面权限受用户授权限制。每次打开投屏浏览器都会弹出一个屏幕选择窗口由用户手动确认选择哪个窗口或整个屏幕。这是浏览器安全机制的一部分无法绕过。3. 核心原理拆解投屏插件背后用到的关键技术3.1 屏幕采集getDisplayMedianavigator.mediaDevices.getDisplayMedia()是浏览器提供的屏幕共享 API。调用该方法后浏览器会弹出一个选择窗口用户可以选择共享整个屏幕、某个应用窗口或某个浏览器标签页。调用方式如下const stream await navigator.mediaDevices.getDisplayMedia({ video: true, audio: true });其中video: true表示采集视频轨这是投屏必须的。audio: true表示采集系统音频或标签页音频是否支持取决于浏览器和操作系统。返回的stream是MediaStream对象其中包含视频轨道和可能的音频轨道。这个 API 是浏览器原生提供的不需要额外依赖。需要特别注意的是getDisplayMedia与普通的摄像头麦克风权限不同它没有“永久授权”的概念每次调用都必须由用户重新选择一次共享内容这是为了解决屏幕内容被网页随意采集的隐私问题。在 Chrome 和 Edge 中getDisplayMedia支持很好。在 Safari 中同样支持但 macOS 系统需要先允许浏览器访问“屏幕录制”权限否则采集到的画面可能是黑屏或只有桌面壁纸。3.2 媒体传输WebRTC采集到屏幕流之后下一个问题是如何把它送到接收端浏览器。WebRTCWeb Real-Time Communication是目前浏览器之间实时音视频传输的标准方案。它的优点是浏览器原生支持无需安装插件。提供 UDP 优先的低延迟传输。自动协商最佳编码参数。支持 NAT 穿透适配复杂网络环境。在投屏场景中发送端通过RTCPeerConnection.addTrack()把屏幕流加入连接接收端通过RTCPeerConnection.ontrack事件拿到远端媒体流然后渲染到video标签。WebRTC 的点对点传输架构可以用下面这个简化的流程来表示发送端屏幕采集 ↓ 本地 MediaStream ↓ RTCPeerConnection编码 传输 ↓ 网络P2P 或 TURN 转发 ↓ 接收端 RTCPeerConnection解码 ↓ video 标签播放3.3 信令服务WebSocketWebRTC 传输的是媒体数据但真正建立连接之前两端必须互相交换一些描述信息包括SDP 信息声明自己支持哪些编解码器、分辨率和传输参数。ICE 候选声明自己可用的网络地址和端口协商出可连通的数据通道。这部分信息不能通过 WebRTC 媒体通道传递必须借助外部服务完成这个服务就叫信令服务。最常见的实现方式就是 WebSocket 信令服务器。一个典型的信令流程如下发送端和接收端分别连接同一个 WebSocket 服务并加入同一个“房间”。发送端创建 Offer把 SDP 发给接收端。接收端收到 Offer 后创建 Answer把 SDP 发回发送端。两端各自通过onicecandidate事件收集 ICE 候选并互相转发。当两端都拿到对方的 SDP 和 ICE 候选后媒体连接建立成功。3.4 开源扩展的通用架构结合上面的分析一个浏览器投屏开源扩展通常包含三个部分模块作用常见实现发送端页面采集屏幕流并发送扩展页面或普通网页接收端页面接收并展示画面普通响应式网页信令服务转发 SDP 和 ICE 候选Node.js WebSocket这三个部分可以拆分成独立项目也可以整合在同一个仓库中。大多数开源方案都会把发送端做成 Chrome/Edge 扩展把接收端做成一个纯网页这样接收设备无需安装任何软件。了解了这些底层原理后下面我们通过一个完整的实战项目把投屏流程跑通。4. 环境准备与版本说明4.1 支持范围本实战示例的投屏能力基于以下标准 APIgetDisplayMediaRTCPeerConnectionWebSocket这些 API 在以下浏览器中均有良好支持Google Chrome 较新版本。Microsoft EdgeChromium 内核。Apple Safari较新版本。需要注意Chrome 和 Edge 可以直接加载“解压的扩展程序”进行调试。Safari 无法直接加载 Chrome 扩展但如果你把发送端做成普通网页Safari 同样可以作为投屏发起端。4.2 运行环境建议操作系统Windows、macOS、Linux 均可以实际开发环境为准。浏览器Chrome 或 Edge 做扩展调试。开发工具VS Code 或任意编辑器。Node.js用于运行信令服务建议使用 18 或更高版本。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。4.3 项目结构我们先规划整个项目结构browser-screen-cast/ ├── manifest.json ├── background.js ├── sender.html ├── sender.js ├── receiver.html ├── receiver.js └── server.js其中manifest.jsonChrome/Edge 扩展清单文件。background.js扩展后台脚本点击图标时打开发送端页面。sender.html/sender.js发送端页面负责屏幕采集和 WebRTC 推流。receiver.html/receiver.js接收端页面负责接收并播放画面。server.jsWebSocket 信令服务负责转发 SDP 和 ICE 候选。5. 完整实战从零搭建一个浏览器投屏演示项目5.1 创建项目结构在命令行中创建项目目录mkdir browser-screen-cast cd browser-screen-cast然后在项目目录下创建上面规划的所有文件。如果你使用 VS Code可以直接使用侧边栏新建文件。5.2 创建扩展清单 manifest.json在项目根目录创建manifest.json文件内容如下{ manifest_version: 3, name: Browser Screen Cast Demo, description: 一个基于 WebRTC 的浏览器投屏演示扩展, version: 1.0.0, action: { default_title: 打开投屏发送端 }, background: { service_worker: background.js }, permissions: [], host_permissions: [ http://localhost/*, ws://localhost/* ], content_security_policy: { extension_pages: script-src self; object-src self; connect-src ws://localhost:8080 http://localhost:8080 } }这里需要注意几个配置项manifest_version: 3是 Chrome 扩展当前推荐使用的清单版本Edge 同样支持。action用来配置浏览器工具栏中的扩展图标点击后触发background.js中的事件。permissions保持为空数组只声明最少权限避免扩展上架审核时因为权限过大被拒。host_permissions声明对localhost的 HTTP 和 WebSocket 访问权限。content_security_policy中允许扩展页面连接本地8080端口的 WebSocket 服务。如果你希望扩展投屏支持局域网内其他机器的信令服务需要把localhost改为你的实际服务地址并在host_permissions中声明对应域名。5.3 编写扩展后台脚本 background.js创建background.js功能非常简单点击扩展图标时打开发送端页面。chrome.action.onClicked.addListener(() { chrome.tabs.create({ url: chrome.runtime.getURL(sender.html) }); });在 Manifest V3 中chrome.action.onClicked事件只会在扩展没有设置default_popup时触发。我们这里没有配置default_popup所以点击图标后会执行后台脚本中的逻辑。5.4 编写发送端页面 sender.html创建sender.html这个页面是投屏发起端包含一个开始投屏按钮和一个视频预览区域。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title浏览器投屏发送端/title style body { font-family: system-ui, -apple-system, sans-serif; max-width: 720px; margin: 40px auto; padding: 0 20px; background: #f7f8fa; color: #333; } h1 { font-size: 20px; } video { width: 100%; max-height: 480px; background: #000; border-radius: 8px; margin: 16px 0; } button { padding: 10px 20px; background: #1a73e8; color: #fff; border: none; border-radius: 6px; font-size: 14px; cursor: pointer; } button:disabled { background: #aaa; cursor: not-allowed; } .status { margin-top: 12px; font-size: 13px; color: #666; } /style /head body h1投屏发送端/h1 p点击一下开始投屏浏览器会弹出屏幕共享选择窗口。/p button idstart开始投屏/button video idpreview autoplay muted/video div idstatus classstatus当前状态未连接/div script srcsender.js/script /body /html5.5 编写发送端核心逻辑 sender.js创建sender.js这段代码是投屏发送端的核心逻辑。// 信令服务地址 const SIGNAL_SERVER ws://localhost:8080; const ROOM_ID demo-room; const video document.getElementById(preview); const status document.getElementById(status); const startBtn document.getElementById(start); let localStream; let pc; // 建立 WebSocket 连接 const socket new WebSocket(SIGNAL_SERVER); socket.addEventListener(open, () { console.log(信令服务连接成功); socket.send(JSON.stringify({ type: join, room: ROOM_ID, role: sender })); }); socket.addEventListener(message, async (event) { const msg JSON.parse(event.data); if (msg.type answer) { // 接收端返回了 Answer设置远端描述 await pc.setRemoteDescription(msg.sdp); console.log(已设置远端 Answer); status.textContent 当前状态已建立连接; } else if (msg.type candidate) { // 收到接收端的 ICE 候选 try { await pc.addIceCandidate(msg.candidate); console.log(已添加接收端 ICE 候选); } catch (e) { console.error(添加 ICE 候选失败, e); } } }); // 创建 RTCPeerConnection function createPeerConnection() { pc new RTCPeerConnection({ iceServers: [ { urls: stun:stun.l.google.com:19302 } ] }); // 收集 ICE 候选并发送给接收端 pc.addEventListener(icecandidate, (event) { if (event.candidate) { socket.send(JSON.stringify({ type: candidate, candidate: event.candidate })); } }); // 监听连接状态变化 pc.addEventListener(connectionstatechange, () { console.log(连接状态, pc.connectionState); }); // 添加屏幕流的轨道 localStream.getTracks().forEach((track) { pc.addTrack(track, localStream); }); } // 开始采集屏幕并发送 async function startShare() { try { localStream await navigator.mediaDevices.getDisplayMedia({ video: true, audio: true }); video.srcObject localStream; status.textContent 当前状态屏幕已采集正在建立连接...; createPeerConnection(); // 创建并发送 Offer const offer await pc.createOffer(); await pc.setLocalDescription(offer); console.log(Offer 已创建); socket.send(JSON.stringify({ type: offer, sdp: pc.localDescription })); startBtn.disabled true; } catch (err) { console.error(屏幕采集失败, err); status.textContent 当前状态采集失败请重试; } } startBtn.addEventListener(click, startShare);代码说明页面加载后自动连接 WebSocket 信令服务并加入demo-room房间角色为sender。点击“开始投屏”按钮后调用getDisplayMedia采集屏幕流。把屏幕流加入RTCPeerConnection。创建 Offer 并通过 WebSocket 发给接收端。接收端创建 Answer 后发回发送端调用setRemoteDescription完成连接协商。icecandidate事件会把本地网络候选发送给接收端用于打通媒体传输路径。5.6 编写接收端页面 receiver.html创建receiver.html接收端是一个独立网页不需要安装扩展直接在任意浏览器的现代浏览器中打开即可。为了方便演示我们让它嵌入在同一个项目目录中部署时也可以单独部署。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title浏览器投屏接收端/title style body { margin: 0; background: #111; height: 100vh; display: flex; align-items: center; justify-content: center; } video { width: 100%; height: 100%; object-fit: contain; background: #000; } .tip { position: fixed; top: 20px; left: 50%; transform: translateX(-50%); color: #fff; background: rgba(0, 0, 0, 0.7); padding: 10px 18px; border-radius: 8px; font-size: 14px; z-index: 99; } /style /head body video idscreen autoplay playsinline/video div classtip idtip等待发送端连接.../div script srcreceiver.js/script /body /html5.7 编写接收端核心逻辑 receiver.js创建receiver.js接收端会监听 WebSocket 消息收到 Offer 后自动生成 Answer并把收到的媒体流渲染到页面。const SIGNAL_SERVER ws://localhost:8080; const ROOM_ID demo-room; const video document.getElementById(screen); const tip document.getElementById(tip); const socket new WebSocket(SIGNAL_SERVER); const pc new RTCPeerConnection({ iceServers: [ { urls: stun:stun.l.google.com:19302 } ] }); // 如果候选早于远端描述到达先放入队列 let pendingCandidates []; // 监听远端媒体流 pc.addEventListener(track, (event) { console.log(收到远端媒体流, event.streams); if (!video.srcObject) { video.srcObject event.streams[0]; tip.textContent 投屏连接成功; } }); // 收集 ICE 候选并发送给发送端 pc.addEventListener(icecandidate, (event) { if (event.candidate) { socket.send(JSON.stringify({ type: candidate, candidate: event.candidate })); } }); socket.addEventListener(open, () { console.log(信令服务连接成功); socket.send(JSON.stringify({ type: join, room: ROOM_ID, role: receiver })); }); socket.addEventListener(message, async (event) { const msg JSON.parse(event.data); if (msg.type offer) { console.log(收到发送端 Offer); await pc.setRemoteDescription(msg.sdp); const answer await pc.createAnswer(); await pc.setLocalDescription(answer); socket.send(JSON.stringify({ type: answer, sdp: pc.localDescription })); // 远端描述已设置补发之前暂存的候选 if (pendingCandidates.length 0) { pendingCandidates.forEach(async (candidate) { try { await pc.addIceCandidate(candidate); console.log(已补发暂存候选); } catch (e) { console.error(补发候选失败, e); } }); pendingCandidates []; } } else if (msg.type candidate) { if (pc.remoteDescription) { await pc.addIceCandidate(msg.candidate); } else { pendingCandidates.push(msg.candidate); } } });接收端代码处理了一个实际项目中常见的时序问题ICE 候选可能早于 Offer/Answer 交换完成就到达此时remoteDescription尚未建立直接调用addIceCandidate会报错。因此我们先把候选放入pendingCandidates队列等设置完远端描述后再统一补充。5.8 编写信令服务 server.js创建server.js使用 Node.js 的ws库实现 WebSocket 信令服务。这个服务的主要职责是按照房间转发消息。首先在项目目录安装依赖npm init -y npm install ws然后编写server.jsconst WebSocket require(ws); const PORT 8080; const wss new WebSocket.Server({ port: PORT }); // 保存每个房间中的 sender 和 receiver 连接 const rooms {}; function getRoom(room) { if (!rooms[room]) { rooms[room] {}; } return rooms[room]; } function getPeer(room, role) { const clients getRoom(room); return role sender ? clients.receiver : clients.sender; } wss.on(connection, (ws) { console.log(有客户端连接接入); ws.on(message, (message) { let data; try { data JSON.parse(message.toString()); } catch (e) { console.error(消息解析失败, message.toString()); return; } if (data.type join) { const { room, role } data; const clients getRoom(room); clients[role] ws; ws.room room; ws.role role; console.log(${role} 加入了房间 ${room}); return; } // 普通消息转发给同一房间中的对端 const peer getPeer(ws.room, ws.role); if (peer peer.readyState WebSocket.OPEN) { peer.send(JSON.stringify(data)); } else { console.log(未找到对端连接无法转发消息); } }); ws.on(close, () { if (ws.room rooms[ws.room]) { delete rooms[ws.room][ws.role]; console.log(客户端断开${ws.role} 离开房间 ${ws.room}); } }); }); console.log(信令服务已启动ws://localhost:${PORT});启动命令node server.js预期输出信令服务已启动ws://localhost:80805.9 加载扩展并运行验证第一步启动信令服务在项目目录执行node server.js保持终端窗口不要关闭。第二步加载扩展打开 Chrome 或 Edge 浏览器在地址栏输入以下地址Chromechrome://extensions/Edgeedge://extensions/开启页面右上角的“开发者模式”然后点击“加载已解压的扩展程序”选择browser-screen-cast项目目录。加载成功后浏览器工具栏会出现扩展图标。第三步打开接收端在另一个设备或同一台电脑的另一个浏览器窗口中打开http://localhost:8080注意这里因为接收端和信令服务都在同一台机器上我们直接用http://localhost:8080访问静态页面。但我们的server.js并没有静态文件服务器功能所以你需要用 VS Code 的 Live Server 或其他静态服务器打开receiver.html。简化方案在项目目录下再启动一个静态服务器npx serve .然后用它提供的地址访问receiver.html例如http://localhost:3000/receiver.html。同时保持信令服务在8080端口运行。第四步发起投屏点击浏览器工具栏中的扩展图标打开发送端页面。点击“开始投屏”按钮在弹出的窗口中选择要共享的屏幕、窗口或标签页然后点击“共享”。此时接收端页面会自动出现发送端的画面说明投屏连接成功。5.10 预期结果说明整个演示跑通后你会观察到发送端页面的video标签会显示预览画面。接收端页面的video标签会同步显示相同画面。两端浏览器的控制台中会打印 WebRTC 连接状态日志。浏览器地址栏附近会出现“正在共享屏幕”等安全提示。这个最小 demo 已经具备了浏览器投屏的核心能力。你可以把它继续扩展为支持房间密码、多接收端、录制回放等更完整的产品。# 补充命令停止信令服务 # 在运行 server.js 的终端中按 Ctrl C 即可6. 常见问题与排查思路实际使用浏览器投屏扩展时会遇到很多看起来和代码无关的系统级、浏览器级问题。下面整理一份高频问题排查表按遇到概率排序。问题现象常见原因解决思路Chrome 下载项目压缩包时提示“文件可能已被篡改”下载源不是 HTTPS或下载的文件校验值不一致改用 HTTPS 下载自己构建项目并对比压缩包哈希扩展安装按钮置灰无法安装未开启开发者模式或扩展包格式不对在chrome://extensions/开启“开发者模式”使用“加载已解压的扩展程序”Edge 无法安装第三方 crx 扩展Edge 默认只信任商店扩展改用“加载解压的扩展”方式或发布到 Edge 加载项商店屏幕共享后画面黑屏macOS 屏幕录制权限未开启在“系统设置 → 隐私与安全性 → 屏幕录制”中勾选浏览器无法选择音频只有画面没有声音部分浏览器不支持采集系统音频或系统音频设置未开启在getDisplayMedia中设置audio: true部分场景需要额外配置WebRTC 连接一直处于 connecting 状态STUN 服务器不可达或浏览器禁止了 UDP检查网络配置可用的 STUN/TURN 服务器接收端报addIceCandidate失败ICE 候选在远端描述设置之前到达使用候选队列等remoteDescription设置后再添加Safari 无法加载 Chrome 扩展Safari 与 Chrome 扩展体系不同用网页模式的投屏发送端或者通过 Xcode 转换 Safari Web ExtensionLinux 下 Edge/Chrome 弹出“密钥环认证窗口”浏览器访问系统钥匙串需要认证安装并配置gnome-keyring或使用其他免交互的钥匙串方案下面挑几个典型问题做详细说明。6.1 Chrome 阻止下载或不信任提示如果你从非官方渠道下载投屏扩展压缩包Chrome 常常会提示由于网站未使用安全连接且文件可能已被篡改因此 Chrome 阻止了此次下载。这个提示本质上是浏览器对下载文件的安全保护机制并不一定说明扩展有问题但也不能完全放松警惕。处理方式有两种从官方应用商店或可信源下载并把项目源码与官方释出的哈希值进行比对。如果只是本地开发使用不通过下载 crx 的方式安装而是直接“加载已解压的扩展程序”。我自己开发时更推荐第二种方式因为本地加载扩展不会经过下载校验还能直接编辑代码即时生效。6.2 扩展安装失败在 Chrome 或 Edge 中点击“加载已解压的扩展程序”后如果目录中没有manifest.json或者manifest.json语法错误浏览器会直接报错。排查步骤确认选择的目录中包含manifest.json而不是选成了外层文件夹。用编辑器检查manifest.json是否为合法 JSON末尾不能有多余逗号。确认没有重复加载两个相同 ID 的扩展。查看chrome://extensions页面底部的错误提示。Edge 用户如果遇到“扩展安装失败无法读取数据目录”的报错通常和浏览器用户数据目录权限有关可以考虑备份后重新指定用户数据目录但要注意先确认数据安全。6.3 WebRTC 一直连接不上如果接收端一直显示“等待发送端连接”而发送端显示“正在建立连接”最可能是信令服务和 WebRTC 协商没有完成。按顺序检查发送端页面控制台是否有 WebSocket 连接失败报错。信令服务终端是否打印了sender 加入了房间和receiver 加入了房间。发送端是否成功创建了 Offer 并发送。接收端是否收到了 Offer 并返回了 Answer。STUN 服务器是否可达开发时可以直接在浏览器访问stun:stun.l.google.com:19302的连通性。如果跨网络投屏必须配置 TURN 服务器否则即使信令正常媒体数据也可能被 NAT 防火墙阻断。6.4 屏幕采集黑屏黑屏问题最常见于 macOS 系统。Safari 或 Chrome 在首次调用getDisplayMedia时系统会询问是否允许屏幕录制。如果你点过“拒绝”需要去“系统设置 → 隐私与安全性 → 屏幕录制”中手动打开对应浏览器的权限。Windows 下黑屏通常是采集对象选择错误或者显卡驱动与浏览器兼容性问题可以尝试切换共享窗口、调整屏幕分辨率或更新显卡驱动。6.5 Safari 和 Chrome 扩展的兼容问题很多开源投屏插件是针对 Chrome/Edge 开发的Safari 无法直接使用同一个.crx文件。Safari 的 Web Extension 机制需要通过 Xcode 的“Safari Web Extension Converter”进行转换转换后还需要重新签名才能安装。如果只是普通网页投屏Safari 完全可以直接使用。也就是说Linux/Windows/Chrome 用户可以安装扩展。Mac 上的 Safari 用户可以采用普通网页版发送端。本文示例中的发送端逻辑是纯页面代码因此即使不装扩展也可以直接用sender.html作为发送端只是入口不如扩展图标方便。7. 最佳实践与工程建议7.1 权限最小化设计开发浏览器投屏扩展时权限声明要遵循最小化原则。Manifest V3 中权限越多上架审核越慢用户安装时也会看到更多风险提示。对于投屏功能通常只需要涉及屏幕采集页面和 WebSocket 通信并不需要申请历史记录、书签、所有网站数据等无关权限。推荐做法只在host_permissions中声明信令服务域名。尽量使用页面级权限避免使用tabs、storage等不必要的权限。在代码中不要读取或上传用户的任何非投屏内容。7.2 安全边界与合规屏幕共享天然涉及敏感信息比如聊天窗口、密码输入框、后台管理系统等。开发和使用投屏工具时必须建立清晰的安全边界。生产环境需要注意信令服务必须使用 WSSWebSocket Secure加密传输避免 SDP/ICE 数据被截获。扩展正式上架时要使用正规开发者账号签名。远程投屏场景需要加入房间鉴权和白名单机制防止任意设备接入。在发送端页面明确提醒用户不要共享包含敏感信息的屏幕区域。投屏过程中建议在页面上显示“正在共享”的明显提示方便操作者随时停止。7.3 网络与延迟优化投屏体验最直观的指标就是延迟和清晰度。局域网内投屏延迟一般可以控制在 100~300 毫秒公网投屏则需要更复杂的网络优化。优化方向包括接收端和发送端尽量处于同一局域网减少 NAT 穿透难度。服务端部署 TURN 服务器时选择与用户网络路径较近的机房。根据网络带宽动态调整视频分辨率避免长时间卡顿。在发送端限制最大码率和帧率防止弱网时音频和画面同时劣化。使用RTCPeerConnection.getStats()接口采集网络延迟和丢包率用于前端监控和报警。示例发送端在创建媒体流后可以限制视频轨道码率const sender pc.getSenders().find((s) s.track s.track.kind video); const params sender.getParameters(); if (!params.encodings) { params.encodings [{}]; } params.encodings[0].maxBitrate 2_500_000; await sender.setParameters(params);这里maxBitrate的单位是 bps2_500_000表示约 2.5 Mbps适合 1080p 画面的局域网投屏。7.4 日志与可观测性WebRTC 排错难度比普通 HTTP 请求高很多因为媒体链路涉及多个环节。强烈建议在开发阶段把以下日志打印到控制台WebSocket 连接状态。pc.connectionState状态变化包括new、connecting、connected、failed等。ICE 候选的收集数量。远端媒体流的轨道信息。Chrome 和 Edge 浏览器还内置了 WebRTC 调试页面chrome://webrtc-internals。当连接异常时打开这个页面可以查看 SDP 内容、ICE 候选、候选对、带宽估计等详细信息是排查 WebRTC 问题最有力的工具。7.5 生产环境的架构演进本文演示的是最简单的“单发送端 单接收端”架构。实际生产环境中投屏需求往往更复杂多接收端一个屏幕同时投给多个观众如果都走 P2P 点对点连接发送端上行带宽会成为瓶颈。这时需要引入 SFUSelective Forwarding Unit服务器由服务器统一接收上游流并分发到多个下游。录制与回放在信令服务之外增加录制模块把媒体流转存到云存储。动态房间管理通过数据库管理房间状态、用户授权和投屏记录。移动端适配接收端页面需要兼容手机屏幕Vue/React 项目可以直接封装一个接收页面组件。对于大部分企业内部工具直接采用“扩展发送端 网页接收端 WebSocket 信令 可选 TURN”的方案已经足够。如果要做大规模运营级产品再考虑迁移到 SFU 架构。8. 总结与接下来可以学什么本文从零拆解了浏览器投屏开源插件背后的技术链路并完成了一个最小可运行项目。通过这个项目你应该已经掌握getDisplayMedia屏幕采集 API 的用法和权限限制。WebRTC 建立点对点连接的完整流程Offer、Answer、ICE 候选交换。WebSocket 信令服务器的作用和实现方式。Chrome/Edge 扩展的 Manifest V3 基础结构。Safari 与 Chrome/Edge 在投屏能力上的差异。从网络、权限、浏览器安全机制到生产环境部署的常见坑点。如果你想继续深入下一步可以优先学习这几个方向WebRTC 高级特性通过getStats分析延迟和丢包掌握带宽自适应算法。SFU 架构了解 mediasoup、Janus、LiveKit 等开源服务器的设计思路。屏幕采集进阶研究tabCapture、chrome.desktopCapture等扩展专属 API。跨端适配把投屏接收页做成移动端优先的 H5并接入会议系统或教学系统。如果你是把投屏能力集成到公司内部系统建议先从小范围试用开始重点验证网络环境和权限策略确认稳定后再逐步放开。遇到具体报错时优先使用浏览器控制台和chrome://webrtc-internals抓取第一手数据定位问题会快很多。希望这篇文章能帮你少走一些弯路。如果文中的示例代码或排查思路对你有帮助欢迎收藏备用。 
长河君 · 2026/8/31 21:57:02 · 阅读 1.2k 基于WebRTC与getDisplayMedia的浏览器投屏方案：从原理到开源扩展实战
平时在做项目演示、客户端联调或远程教学时经常需要把浏览器页面、桌面窗口甚至整个屏幕投到另一个屏幕上。传统的做法是装第三方投屏软件要么收费要么有广告要么在局域网里识别不到设备折腾一圈下来比写业务代码还累。后来调研了一圈发现直接基于浏览器本身就能实现跨设备投屏而且核心能力全部来自浏览器原生 API再配合一个开源扩展外壳就能在 Chrome、Edge 甚至 Safari 中使用同一套投屏逻辑。这篇文章就把这套方案的原理、代码和踩坑记录完整拆解出来方便有类似需求的同学直接复用。本文适合以下几类读者想把浏览器内容投到另一台电脑、电视或投影设备的开发者。负责团队内部会议、教学演示、直播推流工具选型/开发的技术同学。想了解getDisplayMedia、WebRTC、信令服务、浏览器扩展开发的进阶学习者。读完本文后你将掌握浏览器投屏的完整架构和核心原理。Chrome、Edge、Safari 下投屏能力的使用差异。一个最小可运行的投屏 demo 的源码实现。常见报错和坑点的排查方法。生产环境落地时的工程建议。下面我们直接进入正题。1. 浏览器投屏到底是什么解决什么问题1.1 浏览器投屏的定义浏览器投屏指的是以浏览器作为投屏发起端或接收端把浏览器标签页、窗口或整个桌面屏幕的内容通过 WebRTC、WebSocket 等技术传输到另一台设备的浏览器中进行播放和展示。它和手机投电视的场景类似但不需要专门的投屏协议芯片也不需要安装额外的视频播放客户端。只要发起端和接收端的设备都有现代浏览器就能完成整个投屏链路。典型流程可以简化为发起端浏览器采集屏幕画面。通过 WebRTC 建立点对点媒体通道。接收端浏览器解码并播放画面。两端之间通过信令服务协调连接参数。这种方式最大的亮点在于所有媒体采集、编码、传输、解码和播放能力都是浏览器自带的能力开发者不用关心复杂的音视频编码细节也不用购买第三方投屏 SDK。1.2 它能解决什么问题传统投屏方案的痛点很明显系统级投屏如 Miracast、AirPlay、DLNA虽然方便但对设备和系统版本有严格限制。Windows 电脑和 iPhone 之间、安卓手机和 Mac 之间经常互相不兼容。第三方投屏软件需要两端都安装客户端还要注册账号、联网鉴权使用门槛高。会议室专用投屏盒子成本高不适合临时场景。投屏时经常被软件广告弹窗干扰体验不好。而浏览器投屏只需要一个浏览器页面或浏览器扩展就能在局域网内完成投屏。尤其适合以下场景使用场景传统方案浏览器投屏方案技术会议分享代码需要投屏硬件或软件打开接收端网页即可远程联调演示使用视频会议软件通过 WebRTC 自建低延迟通道直播录屏推流需要 OBS 等客户端浏览器直接采集并传输产品 Demo 演示需要特定投屏协议支持 Chrome、Edge、Safari 的通用方案1.3 为什么开发者需要掌握浏览器投屏背后并不是什么黑科技而是 Google、Apple、Microsoft 等浏览器厂商共同推进的 Web 标准能力组合。掌握这套能力不仅能用现成开源插件快速实现投屏还能根据业务需求定制开发把投屏能力集成到自己的网页管理后台中。在会议系统、在线教育、远程协助产品中加入浏览器分享能力。改造现有直播推流工具减少客户端安装依赖。从就业和项目角度来说getDisplayMedia WebRTC 已经是音视频和前端领域的核心技能组合学习价值很高。2. 技术方案选型为什么推荐浏览器扩展方案2.1 主流投屏方案对比我整理了一张对比表方便理解不同方案的适用边界对比维度系统级投屏第三方投屏软件浏览器扩展投屏安装成本系统自带无需安装两端都要安装客户端只需要安装一个扩展或打开网页跨平台能力受品牌和系统限制一般支持主流平台只要浏览器支持 WebRTC 即可延迟表现较好取决于软件实现局域网内通常 100~300 毫秒自定义能力低较低高可完全自定义稳定性受系统和驱动影响依赖服务商依赖浏览器和网络环境成本无需额外成本高级功能常收费开源方案免费可自建从表格可以看出浏览器扩展方案的灵活性是最好的。尤其是在企业内部已有 Web 技术栈的情况下用一套网页代码就能同时覆盖多种设备。2.2 浏览器扩展方案的优势具体来说选择浏览器扩展做投屏有以下几点优势第一安装门槛低。Chrome 和 Edge 都支持开发者模式加载扩展也可以发布到官方商店。用户不需要理解复杂的网络协议点一下扩展图标就能进入发送端页面。第二能力接近原生应用。通过getDisplayMediaAPI扩展可以直接采集屏幕画面通过tabCapture或desktopCapturerElectron 场景还能做更多细粒度的标签页采集。第三代码可复用。扩展内部本质上是 HTML、CSS 和 JavaScript和普通网页技术栈完全一致。你把投屏逻辑写成一个网页再通过扩展包装一层就能获得浏览器级的权限和入口。第四开源生态成熟。开源社区里已经有多个基于 WebRTC 的浏览器投屏项目思路和结构都比较成熟可以直接参考。2.3 方案需要注意的边界浏览器投屏并不是万能的有几个边界需要提前了解Safari 不支持直接安装 Chrome/Edge 的 crx 扩展。但 Safari 支持 Web Extension 的转换机制也支持getDisplayMedia屏幕共享 API因此投屏页面在 Safari 中是可用的只是扩展形态需要单独适配。WebRTC 在公网环境下依赖 STUN/TURN 服务器。如果只是局域网投屏可以不用配置跨网络投屏时必须部署至少一个 TURN 服务器用于 NAT 穿透和媒体转发。浏览器页面权限受用户授权限制。每次打开投屏浏览器都会弹出一个屏幕选择窗口由用户手动确认选择哪个窗口或整个屏幕。这是浏览器安全机制的一部分无法绕过。3. 核心原理拆解投屏插件背后用到的关键技术3.1 屏幕采集getDisplayMedianavigator.mediaDevices.getDisplayMedia()是浏览器提供的屏幕共享 API。调用该方法后浏览器会弹出一个选择窗口用户可以选择共享整个屏幕、某个应用窗口或某个浏览器标签页。调用方式如下const stream await navigator.mediaDevices.getDisplayMedia({ video: true, audio: true });其中video: true表示采集视频轨这是投屏必须的。audio: true表示采集系统音频或标签页音频是否支持取决于浏览器和操作系统。返回的stream是MediaStream对象其中包含视频轨道和可能的音频轨道。这个 API 是浏览器原生提供的不需要额外依赖。需要特别注意的是getDisplayMedia与普通的摄像头麦克风权限不同它没有“永久授权”的概念每次调用都必须由用户重新选择一次共享内容这是为了解决屏幕内容被网页随意采集的隐私问题。在 Chrome 和 Edge 中getDisplayMedia支持很好。在 Safari 中同样支持但 macOS 系统需要先允许浏览器访问“屏幕录制”权限否则采集到的画面可能是黑屏或只有桌面壁纸。3.2 媒体传输WebRTC采集到屏幕流之后下一个问题是如何把它送到接收端浏览器。WebRTCWeb Real-Time Communication是目前浏览器之间实时音视频传输的标准方案。它的优点是浏览器原生支持无需安装插件。提供 UDP 优先的低延迟传输。自动协商最佳编码参数。支持 NAT 穿透适配复杂网络环境。在投屏场景中发送端通过RTCPeerConnection.addTrack()把屏幕流加入连接接收端通过RTCPeerConnection.ontrack事件拿到远端媒体流然后渲染到video标签。WebRTC 的点对点传输架构可以用下面这个简化的流程来表示发送端屏幕采集 ↓ 本地 MediaStream ↓ RTCPeerConnection编码 传输 ↓ 网络P2P 或 TURN 转发 ↓ 接收端 RTCPeerConnection解码 ↓ video 标签播放3.3 信令服务WebSocketWebRTC 传输的是媒体数据但真正建立连接之前两端必须互相交换一些描述信息包括SDP 信息声明自己支持哪些编解码器、分辨率和传输参数。ICE 候选声明自己可用的网络地址和端口协商出可连通的数据通道。这部分信息不能通过 WebRTC 媒体通道传递必须借助外部服务完成这个服务就叫信令服务。最常见的实现方式就是 WebSocket 信令服务器。一个典型的信令流程如下发送端和接收端分别连接同一个 WebSocket 服务并加入同一个“房间”。发送端创建 Offer把 SDP 发给接收端。接收端收到 Offer 后创建 Answer把 SDP 发回发送端。两端各自通过onicecandidate事件收集 ICE 候选并互相转发。当两端都拿到对方的 SDP 和 ICE 候选后媒体连接建立成功。3.4 开源扩展的通用架构结合上面的分析一个浏览器投屏开源扩展通常包含三个部分模块作用常见实现发送端页面采集屏幕流并发送扩展页面或普通网页接收端页面接收并展示画面普通响应式网页信令服务转发 SDP 和 ICE 候选Node.js WebSocket这三个部分可以拆分成独立项目也可以整合在同一个仓库中。大多数开源方案都会把发送端做成 Chrome/Edge 扩展把接收端做成一个纯网页这样接收设备无需安装任何软件。了解了这些底层原理后下面我们通过一个完整的实战项目把投屏流程跑通。4. 环境准备与版本说明4.1 支持范围本实战示例的投屏能力基于以下标准 APIgetDisplayMediaRTCPeerConnectionWebSocket这些 API 在以下浏览器中均有良好支持Google Chrome 较新版本。Microsoft EdgeChromium 内核。Apple Safari较新版本。需要注意Chrome 和 Edge 可以直接加载“解压的扩展程序”进行调试。Safari 无法直接加载 Chrome 扩展但如果你把发送端做成普通网页Safari 同样可以作为投屏发起端。4.2 运行环境建议操作系统Windows、macOS、Linux 均可以实际开发环境为准。浏览器Chrome 或 Edge 做扩展调试。开发工具VS Code 或任意编辑器。Node.js用于运行信令服务建议使用 18 或更高版本。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。4.3 项目结构我们先规划整个项目结构browser-screen-cast/ ├── manifest.json ├── background.js ├── sender.html ├── sender.js ├── receiver.html ├── receiver.js └── server.js其中manifest.jsonChrome/Edge 扩展清单文件。background.js扩展后台脚本点击图标时打开发送端页面。sender.html/sender.js发送端页面负责屏幕采集和 WebRTC 推流。receiver.html/receiver.js接收端页面负责接收并播放画面。server.jsWebSocket 信令服务负责转发 SDP 和 ICE 候选。5. 完整实战从零搭建一个浏览器投屏演示项目5.1 创建项目结构在命令行中创建项目目录mkdir browser-screen-cast cd browser-screen-cast然后在项目目录下创建上面规划的所有文件。如果你使用 VS Code可以直接使用侧边栏新建文件。5.2 创建扩展清单 manifest.json在项目根目录创建manifest.json文件内容如下{ manifest_version: 3, name: Browser Screen Cast Demo, description: 一个基于 WebRTC 的浏览器投屏演示扩展, version: 1.0.0, action: { default_title: 打开投屏发送端 }, background: { service_worker: background.js }, permissions: [], host_permissions: [ http://localhost/*, ws://localhost/* ], content_security_policy: { extension_pages: script-src self; object-src self; connect-src ws://localhost:8080 http://localhost:8080 } }这里需要注意几个配置项manifest_version: 3是 Chrome 扩展当前推荐使用的清单版本Edge 同样支持。action用来配置浏览器工具栏中的扩展图标点击后触发background.js中的事件。permissions保持为空数组只声明最少权限避免扩展上架审核时因为权限过大被拒。host_permissions声明对localhost的 HTTP 和 WebSocket 访问权限。content_security_policy中允许扩展页面连接本地8080端口的 WebSocket 服务。如果你希望扩展投屏支持局域网内其他机器的信令服务需要把localhost改为你的实际服务地址并在host_permissions中声明对应域名。5.3 编写扩展后台脚本 background.js创建background.js功能非常简单点击扩展图标时打开发送端页面。chrome.action.onClicked.addListener(() { chrome.tabs.create({ url: chrome.runtime.getURL(sender.html) }); });在 Manifest V3 中chrome.action.onClicked事件只会在扩展没有设置default_popup时触发。我们这里没有配置default_popup所以点击图标后会执行后台脚本中的逻辑。5.4 编写发送端页面 sender.html创建sender.html这个页面是投屏发起端包含一个开始投屏按钮和一个视频预览区域。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title浏览器投屏发送端/title style body { font-family: system-ui, -apple-system, sans-serif; max-width: 720px; margin: 40px auto; padding: 0 20px; background: #f7f8fa; color: #333; } h1 { font-size: 20px; } video { width: 100%; max-height: 480px; background: #000; border-radius: 8px; margin: 16px 0; } button { padding: 10px 20px; background: #1a73e8; color: #fff; border: none; border-radius: 6px; font-size: 14px; cursor: pointer; } button:disabled { background: #aaa; cursor: not-allowed; } .status { margin-top: 12px; font-size: 13px; color: #666; } /style /head body h1投屏发送端/h1 p点击一下开始投屏浏览器会弹出屏幕共享选择窗口。/p button idstart开始投屏/button video idpreview autoplay muted/video div idstatus classstatus当前状态未连接/div script srcsender.js/script /body /html5.5 编写发送端核心逻辑 sender.js创建sender.js这段代码是投屏发送端的核心逻辑。// 信令服务地址 const SIGNAL_SERVER ws://localhost:8080; const ROOM_ID demo-room; const video document.getElementById(preview); const status document.getElementById(status); const startBtn document.getElementById(start); let localStream; let pc; // 建立 WebSocket 连接 const socket new WebSocket(SIGNAL_SERVER); socket.addEventListener(open, () { console.log(信令服务连接成功); socket.send(JSON.stringify({ type: join, room: ROOM_ID, role: sender })); }); socket.addEventListener(message, async (event) { const msg JSON.parse(event.data); if (msg.type answer) { // 接收端返回了 Answer设置远端描述 await pc.setRemoteDescription(msg.sdp); console.log(已设置远端 Answer); status.textContent 当前状态已建立连接; } else if (msg.type candidate) { // 收到接收端的 ICE 候选 try { await pc.addIceCandidate(msg.candidate); console.log(已添加接收端 ICE 候选); } catch (e) { console.error(添加 ICE 候选失败, e); } } }); // 创建 RTCPeerConnection function createPeerConnection() { pc new RTCPeerConnection({ iceServers: [ { urls: stun:stun.l.google.com:19302 } ] }); // 收集 ICE 候选并发送给接收端 pc.addEventListener(icecandidate, (event) { if (event.candidate) { socket.send(JSON.stringify({ type: candidate, candidate: event.candidate })); } }); // 监听连接状态变化 pc.addEventListener(connectionstatechange, () { console.log(连接状态, pc.connectionState); }); // 添加屏幕流的轨道 localStream.getTracks().forEach((track) { pc.addTrack(track, localStream); }); } // 开始采集屏幕并发送 async function startShare() { try { localStream await navigator.mediaDevices.getDisplayMedia({ video: true, audio: true }); video.srcObject localStream; status.textContent 当前状态屏幕已采集正在建立连接...; createPeerConnection(); // 创建并发送 Offer const offer await pc.createOffer(); await pc.setLocalDescription(offer); console.log(Offer 已创建); socket.send(JSON.stringify({ type: offer, sdp: pc.localDescription })); startBtn.disabled true; } catch (err) { console.error(屏幕采集失败, err); status.textContent 当前状态采集失败请重试; } } startBtn.addEventListener(click, startShare);代码说明页面加载后自动连接 WebSocket 信令服务并加入demo-room房间角色为sender。点击“开始投屏”按钮后调用getDisplayMedia采集屏幕流。把屏幕流加入RTCPeerConnection。创建 Offer 并通过 WebSocket 发给接收端。接收端创建 Answer 后发回发送端调用setRemoteDescription完成连接协商。icecandidate事件会把本地网络候选发送给接收端用于打通媒体传输路径。5.6 编写接收端页面 receiver.html创建receiver.html接收端是一个独立网页不需要安装扩展直接在任意浏览器的现代浏览器中打开即可。为了方便演示我们让它嵌入在同一个项目目录中部署时也可以单独部署。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title浏览器投屏接收端/title style body { margin: 0; background: #111; height: 100vh; display: flex; align-items: center; justify-content: center; } video { width: 100%; height: 100%; object-fit: contain; background: #000; } .tip { position: fixed; top: 20px; left: 50%; transform: translateX(-50%); color: #fff; background: rgba(0, 0, 0, 0.7); padding: 10px 18px; border-radius: 8px; font-size: 14px; z-index: 99; } /style /head body video idscreen autoplay playsinline/video div classtip idtip等待发送端连接.../div script srcreceiver.js/script /body /html5.7 编写接收端核心逻辑 receiver.js创建receiver.js接收端会监听 WebSocket 消息收到 Offer 后自动生成 Answer并把收到的媒体流渲染到页面。const SIGNAL_SERVER ws://localhost:8080; const ROOM_ID demo-room; const video document.getElementById(screen); const tip document.getElementById(tip); const socket new WebSocket(SIGNAL_SERVER); const pc new RTCPeerConnection({ iceServers: [ { urls: stun:stun.l.google.com:19302 } ] }); // 如果候选早于远端描述到达先放入队列 let pendingCandidates []; // 监听远端媒体流 pc.addEventListener(track, (event) { console.log(收到远端媒体流, event.streams); if (!video.srcObject) { video.srcObject event.streams[0]; tip.textContent 投屏连接成功; } }); // 收集 ICE 候选并发送给发送端 pc.addEventListener(icecandidate, (event) { if (event.candidate) { socket.send(JSON.stringify({ type: candidate, candidate: event.candidate })); } }); socket.addEventListener(open, () { console.log(信令服务连接成功); socket.send(JSON.stringify({ type: join, room: ROOM_ID, role: receiver })); }); socket.addEventListener(message, async (event) { const msg JSON.parse(event.data); if (msg.type offer) { console.log(收到发送端 Offer); await pc.setRemoteDescription(msg.sdp); const answer await pc.createAnswer(); await pc.setLocalDescription(answer); socket.send(JSON.stringify({ type: answer, sdp: pc.localDescription })); // 远端描述已设置补发之前暂存的候选 if (pendingCandidates.length 0) { pendingCandidates.forEach(async (candidate) { try { await pc.addIceCandidate(candidate); console.log(已补发暂存候选); } catch (e) { console.error(补发候选失败, e); } }); pendingCandidates []; } } else if (msg.type candidate) { if (pc.remoteDescription) { await pc.addIceCandidate(msg.candidate); } else { pendingCandidates.push(msg.candidate); } } });接收端代码处理了一个实际项目中常见的时序问题ICE 候选可能早于 Offer/Answer 交换完成就到达此时remoteDescription尚未建立直接调用addIceCandidate会报错。因此我们先把候选放入pendingCandidates队列等设置完远端描述后再统一补充。5.8 编写信令服务 server.js创建server.js使用 Node.js 的ws库实现 WebSocket 信令服务。这个服务的主要职责是按照房间转发消息。首先在项目目录安装依赖npm init -y npm install ws然后编写server.jsconst WebSocket require(ws); const PORT 8080; const wss new WebSocket.Server({ port: PORT }); // 保存每个房间中的 sender 和 receiver 连接 const rooms {}; function getRoom(room) { if (!rooms[room]) { rooms[room] {}; } return rooms[room]; } function getPeer(room, role) { const clients getRoom(room); return role sender ? clients.receiver : clients.sender; } wss.on(connection, (ws) { console.log(有客户端连接接入); ws.on(message, (message) { let data; try { data JSON.parse(message.toString()); } catch (e) { console.error(消息解析失败, message.toString()); return; } if (data.type join) { const { room, role } data; const clients getRoom(room); clients[role] ws; ws.room room; ws.role role; console.log(${role} 加入了房间 ${room}); return; } // 普通消息转发给同一房间中的对端 const peer getPeer(ws.room, ws.role); if (peer peer.readyState WebSocket.OPEN) { peer.send(JSON.stringify(data)); } else { console.log(未找到对端连接无法转发消息); } }); ws.on(close, () { if (ws.room rooms[ws.room]) { delete rooms[ws.room][ws.role]; console.log(客户端断开${ws.role} 离开房间 ${ws.room}); } }); }); console.log(信令服务已启动ws://localhost:${PORT});启动命令node server.js预期输出信令服务已启动ws://localhost:80805.9 加载扩展并运行验证第一步启动信令服务在项目目录执行node server.js保持终端窗口不要关闭。第二步加载扩展打开 Chrome 或 Edge 浏览器在地址栏输入以下地址Chromechrome://extensions/Edgeedge://extensions/开启页面右上角的“开发者模式”然后点击“加载已解压的扩展程序”选择browser-screen-cast项目目录。加载成功后浏览器工具栏会出现扩展图标。第三步打开接收端在另一个设备或同一台电脑的另一个浏览器窗口中打开http://localhost:8080注意这里因为接收端和信令服务都在同一台机器上我们直接用http://localhost:8080访问静态页面。但我们的server.js并没有静态文件服务器功能所以你需要用 VS Code 的 Live Server 或其他静态服务器打开receiver.html。简化方案在项目目录下再启动一个静态服务器npx serve .然后用它提供的地址访问receiver.html例如http://localhost:3000/receiver.html。同时保持信令服务在8080端口运行。第四步发起投屏点击浏览器工具栏中的扩展图标打开发送端页面。点击“开始投屏”按钮在弹出的窗口中选择要共享的屏幕、窗口或标签页然后点击“共享”。此时接收端页面会自动出现发送端的画面说明投屏连接成功。5.10 预期结果说明整个演示跑通后你会观察到发送端页面的video标签会显示预览画面。接收端页面的video标签会同步显示相同画面。两端浏览器的控制台中会打印 WebRTC 连接状态日志。浏览器地址栏附近会出现“正在共享屏幕”等安全提示。这个最小 demo 已经具备了浏览器投屏的核心能力。你可以把它继续扩展为支持房间密码、多接收端、录制回放等更完整的产品。# 补充命令停止信令服务 # 在运行 server.js 的终端中按 Ctrl C 即可6. 常见问题与排查思路实际使用浏览器投屏扩展时会遇到很多看起来和代码无关的系统级、浏览器级问题。下面整理一份高频问题排查表按遇到概率排序。问题现象常见原因解决思路Chrome 下载项目压缩包时提示“文件可能已被篡改”下载源不是 HTTPS或下载的文件校验值不一致改用 HTTPS 下载自己构建项目并对比压缩包哈希扩展安装按钮置灰无法安装未开启开发者模式或扩展包格式不对在chrome://extensions/开启“开发者模式”使用“加载已解压的扩展程序”Edge 无法安装第三方 crx 扩展Edge 默认只信任商店扩展改用“加载解压的扩展”方式或发布到 Edge 加载项商店屏幕共享后画面黑屏macOS 屏幕录制权限未开启在“系统设置 → 隐私与安全性 → 屏幕录制”中勾选浏览器无法选择音频只有画面没有声音部分浏览器不支持采集系统音频或系统音频设置未开启在getDisplayMedia中设置audio: true部分场景需要额外配置WebRTC 连接一直处于 connecting 状态STUN 服务器不可达或浏览器禁止了 UDP检查网络配置可用的 STUN/TURN 服务器接收端报addIceCandidate失败ICE 候选在远端描述设置之前到达使用候选队列等remoteDescription设置后再添加Safari 无法加载 Chrome 扩展Safari 与 Chrome 扩展体系不同用网页模式的投屏发送端或者通过 Xcode 转换 Safari Web ExtensionLinux 下 Edge/Chrome 弹出“密钥环认证窗口”浏览器访问系统钥匙串需要认证安装并配置gnome-keyring或使用其他免交互的钥匙串方案下面挑几个典型问题做详细说明。6.1 Chrome 阻止下载或不信任提示如果你从非官方渠道下载投屏扩展压缩包Chrome 常常会提示由于网站未使用安全连接且文件可能已被篡改因此 Chrome 阻止了此次下载。这个提示本质上是浏览器对下载文件的安全保护机制并不一定说明扩展有问题但也不能完全放松警惕。处理方式有两种从官方应用商店或可信源下载并把项目源码与官方释出的哈希值进行比对。如果只是本地开发使用不通过下载 crx 的方式安装而是直接“加载已解压的扩展程序”。我自己开发时更推荐第二种方式因为本地加载扩展不会经过下载校验还能直接编辑代码即时生效。6.2 扩展安装失败在 Chrome 或 Edge 中点击“加载已解压的扩展程序”后如果目录中没有manifest.json或者manifest.json语法错误浏览器会直接报错。排查步骤确认选择的目录中包含manifest.json而不是选成了外层文件夹。用编辑器检查manifest.json是否为合法 JSON末尾不能有多余逗号。确认没有重复加载两个相同 ID 的扩展。查看chrome://extensions页面底部的错误提示。Edge 用户如果遇到“扩展安装失败无法读取数据目录”的报错通常和浏览器用户数据目录权限有关可以考虑备份后重新指定用户数据目录但要注意先确认数据安全。6.3 WebRTC 一直连接不上如果接收端一直显示“等待发送端连接”而发送端显示“正在建立连接”最可能是信令服务和 WebRTC 协商没有完成。按顺序检查发送端页面控制台是否有 WebSocket 连接失败报错。信令服务终端是否打印了sender 加入了房间和receiver 加入了房间。发送端是否成功创建了 Offer 并发送。接收端是否收到了 Offer 并返回了 Answer。STUN 服务器是否可达开发时可以直接在浏览器访问stun:stun.l.google.com:19302的连通性。如果跨网络投屏必须配置 TURN 服务器否则即使信令正常媒体数据也可能被 NAT 防火墙阻断。6.4 屏幕采集黑屏黑屏问题最常见于 macOS 系统。Safari 或 Chrome 在首次调用getDisplayMedia时系统会询问是否允许屏幕录制。如果你点过“拒绝”需要去“系统设置 → 隐私与安全性 → 屏幕录制”中手动打开对应浏览器的权限。Windows 下黑屏通常是采集对象选择错误或者显卡驱动与浏览器兼容性问题可以尝试切换共享窗口、调整屏幕分辨率或更新显卡驱动。6.5 Safari 和 Chrome 扩展的兼容问题很多开源投屏插件是针对 Chrome/Edge 开发的Safari 无法直接使用同一个.crx文件。Safari 的 Web Extension 机制需要通过 Xcode 的“Safari Web Extension Converter”进行转换转换后还需要重新签名才能安装。如果只是普通网页投屏Safari 完全可以直接使用。也就是说Linux/Windows/Chrome 用户可以安装扩展。Mac 上的 Safari 用户可以采用普通网页版发送端。本文示例中的发送端逻辑是纯页面代码因此即使不装扩展也可以直接用sender.html作为发送端只是入口不如扩展图标方便。7. 最佳实践与工程建议7.1 权限最小化设计开发浏览器投屏扩展时权限声明要遵循最小化原则。Manifest V3 中权限越多上架审核越慢用户安装时也会看到更多风险提示。对于投屏功能通常只需要涉及屏幕采集页面和 WebSocket 通信并不需要申请历史记录、书签、所有网站数据等无关权限。推荐做法只在host_permissions中声明信令服务域名。尽量使用页面级权限避免使用tabs、storage等不必要的权限。在代码中不要读取或上传用户的任何非投屏内容。7.2 安全边界与合规屏幕共享天然涉及敏感信息比如聊天窗口、密码输入框、后台管理系统等。开发和使用投屏工具时必须建立清晰的安全边界。生产环境需要注意信令服务必须使用 WSSWebSocket Secure加密传输避免 SDP/ICE 数据被截获。扩展正式上架时要使用正规开发者账号签名。远程投屏场景需要加入房间鉴权和白名单机制防止任意设备接入。在发送端页面明确提醒用户不要共享包含敏感信息的屏幕区域。投屏过程中建议在页面上显示“正在共享”的明显提示方便操作者随时停止。7.3 网络与延迟优化投屏体验最直观的指标就是延迟和清晰度。局域网内投屏延迟一般可以控制在 100~300 毫秒公网投屏则需要更复杂的网络优化。优化方向包括接收端和发送端尽量处于同一局域网减少 NAT 穿透难度。服务端部署 TURN 服务器时选择与用户网络路径较近的机房。根据网络带宽动态调整视频分辨率避免长时间卡顿。在发送端限制最大码率和帧率防止弱网时音频和画面同时劣化。使用RTCPeerConnection.getStats()接口采集网络延迟和丢包率用于前端监控和报警。示例发送端在创建媒体流后可以限制视频轨道码率const sender pc.getSenders().find((s) s.track s.track.kind video); const params sender.getParameters(); if (!params.encodings) { params.encodings [{}]; } params.encodings[0].maxBitrate 2_500_000; await sender.setParameters(params);这里maxBitrate的单位是 bps2_500_000表示约 2.5 Mbps适合 1080p 画面的局域网投屏。7.4 日志与可观测性WebRTC 排错难度比普通 HTTP 请求高很多因为媒体链路涉及多个环节。强烈建议在开发阶段把以下日志打印到控制台WebSocket 连接状态。pc.connectionState状态变化包括new、connecting、connected、failed等。ICE 候选的收集数量。远端媒体流的轨道信息。Chrome 和 Edge 浏览器还内置了 WebRTC 调试页面chrome://webrtc-internals。当连接异常时打开这个页面可以查看 SDP 内容、ICE 候选、候选对、带宽估计等详细信息是排查 WebRTC 问题最有力的工具。7.5 生产环境的架构演进本文演示的是最简单的“单发送端 单接收端”架构。实际生产环境中投屏需求往往更复杂多接收端一个屏幕同时投给多个观众如果都走 P2P 点对点连接发送端上行带宽会成为瓶颈。这时需要引入 SFUSelective Forwarding Unit服务器由服务器统一接收上游流并分发到多个下游。录制与回放在信令服务之外增加录制模块把媒体流转存到云存储。动态房间管理通过数据库管理房间状态、用户授权和投屏记录。移动端适配接收端页面需要兼容手机屏幕Vue/React 项目可以直接封装一个接收页面组件。对于大部分企业内部工具直接采用“扩展发送端 网页接收端 WebSocket 信令 可选 TURN”的方案已经足够。如果要做大规模运营级产品再考虑迁移到 SFU 架构。8. 总结与接下来可以学什么本文从零拆解了浏览器投屏开源插件背后的技术链路并完成了一个最小可运行项目。通过这个项目你应该已经掌握getDisplayMedia屏幕采集 API 的用法和权限限制。WebRTC 建立点对点连接的完整流程Offer、Answer、ICE 候选交换。WebSocket 信令服务器的作用和实现方式。Chrome/Edge 扩展的 Manifest V3 基础结构。Safari 与 Chrome/Edge 在投屏能力上的差异。从网络、权限、浏览器安全机制到生产环境部署的常见坑点。如果你想继续深入下一步可以优先学习这几个方向WebRTC 高级特性通过getStats分析延迟和丢包掌握带宽自适应算法。SFU 架构了解 mediasoup、Janus、LiveKit 等开源服务器的设计思路。屏幕采集进阶研究tabCapture、chrome.desktopCapture等扩展专属 API。跨端适配把投屏接收页做成移动端优先的 H5并接入会议系统或教学系统。如果你是把投屏能力集成到公司内部系统建议先从小范围试用开始重点验证网络环境和权限策略确认稳定后再逐步放开。遇到具体报错时优先使用浏览器控制台和chrome://webrtc-internals抓取第一手数据定位问题会快很多。希望这篇文章能帮你少走一些弯路。如果文中的示例代码或排查思路对你有帮助欢迎收藏备用。