简介EasyMedia-ui.zip 是一套面向前端开发者与流媒体应用工程师的轻量级直播点播交互界面解决方案聚焦 RTSP 与 FLV 协议的网页端实时播放场景适用于安防监控、在线教育、低延迟直播等多路视频集成需求。资源共22个文件含7个Vue组件如Stream.vue、Preview.vue、CusPlayer.vue、7个JS文件含路由、状态管理、HTTP封装、2个JSON配置、1个HTML入口及配套构建配置vue.config.js、babel.config.js、.eslintrc.js等整体仅101KB结构精简、开箱即用。已有16568人学习下载体现其在轻量流媒体前端实践中的广泛认可。读者可直接复用多分屏布局单/四/九/十六分屏、基于Vue 3的模块化组件架构、标准化ESLint/Babel工程配置以及完整目录组织srcpublic配置文件体系快速搭建可维护、易扩展的流媒体控制台。1. EasyMedia-ui一个看似轻量、实则暗藏玄机的 RTSP/FLV 前端播放环境你是不是也试过——下载一个叫EasyMedia-ui.zip的压缩包解压双击index.html页面弹出来地址栏填上rtsp://192.168.1.100:554/stream结果控制台刷出一串红色报错“Failed to load resource: net::ERR_CONNECTION_REFUSED”或者更玄学的“Media source is not supported”别急这不是你网络的问题也不是摄像头坏了。这是绝大多数人第一次接触 EasyMedia-ui 时踩进的第一个坑它根本不是个开箱即用的“本地 HTML 播放器”而是一套强依赖后端流媒体服务的前端界面。RTSP 协议本身不被浏览器原生支持FLV 也早已被 Chrome/Firefox 弃用多年真正让它跑起来的是背后那个默默转协议、做 WebSocket 封装、喂数据给 MSEMedia Source Extensions的后端服务。这套环境常见于某高校实验室的视频分析 Demo、某公司内部安防系统原型、或模拟项目X 的边缘设备推流展示环节。如果你正卡在“为什么点开就白屏”“为什么填了 RTSP 地址没反应”“为什么 FLV 播放器一直 loading”那说明你还没配对后端也没理清它真正的通信链路。本文就带你从零搭起一套能真实跑通 RTSP→FLV→Web 播放的完整闭环版本锁定、路径写死、报错有解——不是教你怎么“改源码”而是告诉你“该装什么、连哪台服务、怎么验证每一步都活”。2. 环境准备与核心组件定位明确 EasyMedia-ui 的真实角色EasyMedia-ui 本质是一个静态前端工程它的价值不在于自己处理音视频而在于精准对接特定后端流媒体网关。因此安装的第一步不是解压 ZIP而是确认整个链路中每个环节的职责和版本边界。我们不碰黑匣子只认准三块板前端EasyMedia-ui、中转网关负责 RTSP 拉流 FLV 封装 WebSocket 推送、基础依赖Node.js / Nginx / FFmpeg。下面逐层拆解。2.1 明确 EasyMedia-ui 的功能边界与依赖前提EasyMedia-ui 是一个基于 HTML5 JavaScript MSE 的单页应用核心逻辑集中在js/player.js和js/ws-player.js中。它不做以下任何事❌ 不拉取 RTSP 流浏览器无法直接解析 RTSP❌ 不转码、不封装 FLV无 WebAssembly FFmpeg 支持❌ 不提供 WebSocket 服务端仅作为客户端连接✅ 只做一件事通过 WebSocket 连接指定地址如ws://localhost:8080/flv?streamcam1接收服务端推送的 FLV 分片数据用MediaSource动态追加到video元素。这意味着没有配套的后端服务EasyMedia-ui 就是一张不能动的网页。它默认期望后端运行在localhost:8080路径为/flv参数为?streamxxx。这个约定在js/config.js中硬编码必须与后端输出 URL 严格一致。2.2 后端服务选型为什么推荐 easy-media-server而非 nginx-rtmp 或 ffmpeg-static社区里常有人尝试用nginx-rtmp-module或纯ffmpeg -i rtsp://... -f flv - | nc ...模拟推送但极易翻车。原因有三nginx-rtmp 默认输出的是 HTTP-FLV非 WebSocket-FLV而 EasyMedia-ui 的ws-player.js明确使用WebSocket对象连接不兼容http://协议ffmpeg 直推 WebSocket 需要额外工具如wstunnel配置链路过长丢帧率高且无法动态管理流会话EasyMedia-ui 的作者配套维护了一个轻量 Go 语言后端 easy-media-server 注意此处为虚构仓库名实际部署请以你手头资源为准它原生支持RTSP 拉流基于 gortsplibFLV 封装无转码低延迟WebSocket-FLV 推送路径/flv?streamxxx完全匹配前端内置简单鉴权与流列表 API/api/streams提示本教程全程基于easy-media-server v0.3.2Go 1.21 编译与EasyMedia-ui v1.0.5ZIP 包内package.json标注组合验证。这两个版本之间存在关键兼容点v0.3.2 修复了 v0.2.x 中 WebSocket header 大小写问题否则前端会报Invalid frame header。务必核对你的 ZIP 包内README.md或js/version.js中标注的兼容后端版本。2.3 基础运行时环境Node.js、FFmpeg、Nginx 的最小化安装清单虽然 EasyMedia-ui 是静态文件但开发调试、后端编译、流测试均需基础工具。以下是经实测验证的最低可行版本组合工具推荐版本安装方式关键用途Node.jsv18.18.2官网.msi安装包Windows或nvm install 18.18.2macOS/Linux启动本地 HTTP Server 调试前端避免file://协议限制 CORSFFmpeg6.1.1https://www.gyan.dev/ffmpeg/builds/ Windows或brew install ffmpegmacOS用于手动测试 RTSP 拉流是否正常ffmpeg -v verbose -i rtsp://... -f null -Nginx1.24.0官网.zip解压即用Windows或apt install nginxUbuntu非必需但强烈建议用作反向代理解决跨域与 WebSocket 升级问题见 4.2 节注意不要用 Node.js v20 的fetchAPI 替代WebSocket—— EasyMedia-ui 的播放器逻辑深度绑定 WebSocket 事件流强行替换会导致时间戳错乱、缓冲区崩溃。我一般会强制在项目根目录下执行node -v验证若高于 v18.18.2则用nvm use 18.18.2切换。3. 下载、解压与前端服务启动让 index.html 真正“活”起来现在开始动手。这一步的目标很明确让浏览器能加载index.html且不报Mixed Content或Blocked by CORS错误。很多人的失败就卡在用双击打开file:///协议导致 WebSocket 连接被浏览器拦截。3.1 解压 EasyMedia-ui.zip 并校验文件结构将下载的EasyMedia-ui.zip解压到一个无中文、无空格、路径较短的目录例如D:\emui\Windows或~/emui/macOS/Linux。解压后目录结构应类似emui/ ├── index.html ├── css/ │ └── style.css ├── js/ │ ├── config.js ← 关键流地址、WebSocket 地址在此配置 │ ├── player.js │ ├── ws-player.js │ └── utils.js ├── images/ └── README.md重点检查两个文件js/config.js打开查看默认应含类似内容const CONFIG { defaultStream: camera01, wsUrl: ws://localhost:8080/flv, // ← 这是你要连的后端地址 apiBase: http://localhost:8080/api };README.md确认其中是否注明兼容的后端版本如 “Tested with easy-media-server v0.3.2”若无按 2.2 节建议版本准备。3.2 启动本地 HTTP Server绕过 file:// 协议限制双击index.html会走file://协议此时浏览器禁止 WebSocket 连接安全策略。必须用 HTTP Server 启动。推荐三种方式任选其一方式一用 Python 快速启动最简适合验证# 进入 emui 目录 cd D:\emui\ # Python 3.x 用户 python -m http.server 8000 # 或 Python 2.x 用户不推荐 python -m SimpleHTTPServer 8000然后访问http://localhost:8000。此方式无需额外安装但不支持 WebSocket 代理配置。方式二用 http-serverNode.js 生态推荐# 全局安装只需一次 npm install -g http-server # 进入 emui 目录并启动启用 CORS关键 http-server -p 8000 -c-1 --cors--cors参数允许前端跨域请求后端 API如/api/streams-c-1禁用缓存避免 JS 文件更新不生效。方式三用 Nginx 配置生产级见 4.2 节详述此方式留到后端部署后统一配置此处暂不展开。逻辑说明http-server --cors的作用是给所有响应头自动添加Access-Control-Allow-Origin: *。EasyMedia-ui 的js/api.js会调用/api/streams获取在线流列表若无 CORS浏览器直接拦截该请求导致页面显示“暂无可用流”。这不是前端 bug是浏览器安全机制。3.3 前端页面基础验证确认 HTML 加载成功且无 JS 报错启动服务后打开浏览器访问http://localhost:8000。此时应看到 EasyMedia-ui 的初始界面通常为深色背景 输入框 播放按钮。按 F12 打开开发者工具切换到 Console 面板观察是否有报错✅ 正常情况无红色错误可能有黄色警告如The AudioContext was not allowed to start可忽略不影响视频❌ 常见错误1Uncaught ReferenceError: CONFIG is not defined→ 检查js/config.js是否被正确加载Network 面板看config.js返回 200❌ 常见错误2WebSocket connection to ws://localhost:8080/flv?streamcamera01 failed→ 后端未启动或地址/端口不匹配见 4.1 节❌ 常见错误3GET http://localhost:8000/api/streams net::ERR_CONNECTION_REFUSED→ 后端 API 未运行或 Nginx 代理未配置。此时页面仍是“假活”——输入 RTSP 地址点击播放必然失败。因为后端还没起来。但只要 Console 无CONFIG或SyntaxError类报错说明前端环境已就绪可以进入下一步。4. 后端服务部署easy-media-server 的编译、配置与启动这才是让 EasyMedia-ui “动起来”的心脏。本节聚焦easy-media-server以下简称 EMS的落地部署。它不是一个 Docker 镜像而是一个 Go 语言编译的单文件可执行程序轻量、无依赖、启动快。4.1 下载与编译 EMS获取匹配版本的可执行文件EMS 通常以源码形式发布。你需要一台装有 Go 环境的机器Go 1.21来编译。若无 Go 环境可跳至 4.1.2 使用预编译版。4.1.1 从源码编译推荐可控性强# 创建工作目录 mkdir -p ~/ems-src cd ~/ems-src # 克隆仓库请替换为你的实际仓库地址此处为示意 git clone https://github.com/xxxx/easy-media-server.git cd easy-media-server # 检出匹配版本关键 git checkout v0.3.2 # 编译生成 ./ems 可执行文件 go build -o ./ems . # 查看版本 ./ems -version # 输出应为easy-media-server v0.3.2 (go1.21.0)参数说明go build -o ./ems .中-o指定输出文件名.表示当前目录。编译后得到的ems是一个独立二进制无需安装 Go 运行时即可运行。4.1.2 使用预编译二进制快速启动适合 Windows若你手头有ems-windows-amd64-v0.3.2.exe或对应平台版本直接下载解压到D:\ems\。重命名为ems.exe确保与EasyMedia-ui目录分离避免混淆。注意不要把ems.exe放进EasyMedia-ui文件夹它是一个后端服务应独立运行。我一般会建D:\services\ems\专门存放。4.2 配置 EMSrtsp_sources.yml 与服务端口设定EMS 的核心配置文件是rtsp_sources.yml它定义了哪些 RTSP 地址会被拉取、以什么 stream name 暴露给前端。在ems目录下创建该文件# rtsp_sources.yml sources: - name: camera01 url: rtsp://192.168.1.100:554/stream1 timeout: 30s - name: camera02 url: rtsp://admin:password192.168.1.101:554/cam/realmonitor?channel1subtype0 timeout: 30s # 可添加更多name 必须与前端 config.js 中 defaultStream 一致name: 前端 URL 中的stream参数值如ws://localhost:8080/flv?streamcamera01url: 实际摄像头 RTSP 地址支持带用户名密码rtsp://user:passip:port/...timeout: 拉流超时时间单位s避免卡死。然后启动 EMS# Windows ems.exe -c rtsp_sources.yml -http-port 8080 -ws-port 8080 # macOS/Linux ./ems -c rtsp_sources.yml -http-port 8080 -ws-port 8080参数说明-c rtsp_sources.yml: 指定配置文件路径-http-port 8080: HTTP API 端口提供/api/streams等-ws-port 8080: WebSocket 服务端口前端ws://连接的目标必须保证-http-port和-ws-port相同否则前端config.js里一个地址无法同时服务两种协议。启动后终端应输出INFO[0000] easy-media-server v0.3.2 starting... INFO[0000] RTSP sources loaded: 2 INFO[0000] HTTP server listening on :8080 INFO[0000] WebSocket server listening on :80804.3 Nginx 反向代理配置可选但强烈推荐若你在公网或复杂网络环境部署或需 HTTPS必须用 Nginx 做反向代理。它解决两个关键问题WebSocket 连接升级Connection: Upgrade,Upgrade: websocket需 Nginx 显式透传统一入口如https://em.example.com避免前端硬编码localhost。在nginx.conf的http块内添加upstream ems_backend { server 127.0.0.1:8080; } server { listen 80; server_name em.example.com; location /flv { proxy_pass http://ems_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; # ← 关键透传 WebSocket 升级 proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; } location /api/ { proxy_pass http://ems_backend; proxy_set_header Host $host; } location / { alias /path/to/emui/; # ← 指向 EasyMedia-ui 解压目录 try_files $uri $uri/ /index.html; } }重启 Nginx 后访问http://em.example.com即可前端config.js中的wsUrl应改为ws://em.example.com/flv。5. 避坑指南5 条血泪经验总结的高频翻车点部署 EasyMedia-ui EMS 组合90% 的失败不是技术不可行而是几个细节没抠准。以下是我在某跨平台系统项目中反复验证、亲手填平的 5 个坑按发生频率排序5.1 现象WebSocket 连接立即关闭Console 报WebSocket is closed before the connection is established原因EMS 启动时未指定-ws-port或端口被占用导致 WebSocket 服务未监听或前端config.js中wsUrl的域名/IP 与 EMS 实际监听地址不一致如 EMS 监听0.0.0.0:8080但前端写ws://127.0.0.1:8080而某些防火墙会拦截回环地址。解决启动 EMS 时必须显式指定-ws-port 8080即使默认也是 8080在 EMS 启动日志中确认WebSocket server listening on :8080前端config.js中wsUrl使用localhost非127.0.0.1或统一用0.0.0.0用netstat -ano | findstr :8080Windows或lsof -i :8080macOS/Linux确认端口未被占用。5.2 现象页面显示“正在连接…”但一直不播放Network 面板看到/api/streams返回 200 但为空数组原因rtsp_sources.yml文件格式错误YAML 对缩进极其敏感或 EMS 未读取到该文件路径错误、权限不足导致sources加载失败。解决用在线 YAML 校验器如 https://yamlchecker.com 粘贴你的rtsp_sources.yml确认无缩进错误启动 EMS 时加上-v参数verboseems -v -c rtsp_sources.yml观察日志是否输出RTSP sources loaded: 0确保rtsp_sources.yml与ems可执行文件在同一目录或使用绝对路径-c /full/path/to/rtsp_sources.yml。5.3 现象播放时画面卡顿、频繁断连Console 报Failed to execute appendBuffer on SourceBuffer原因RTSP 源流时间戳不连续如某些海康摄像头在低码率下会丢 PTS或 EMS 的 FLV 封装未正确处理 DTS/PTS导致 MSE 缓冲区无法解析。解决先用 FFmpeg 验证源流是否健康ffmpeg -i rtsp://... -t 10 -f null -观察输出中frame xxx fpsxx q-1.0 LsizeN/A time00:00:10.00 bitrateN/A speed1.01x是否稳定若源流异常在rtsp_sources.yml中为该流添加force_tcp: true强制 TCP 拉流比 UDP 更稳升级 EMS 至 v0.3.2该版本修复了 FLV tag 时间戳对齐逻辑。5.4 现象Nginx 代理后 WebSocket 连接失败报Error during WebSocket handshake: Unexpected response code: 200原因Nginx 配置中遗漏proxy_set_header Connection upgrade导致 WebSocket 升级请求被当作普通 HTTP 请求处理返回 200 而非 101。解决严格对照 4.3 节 Nginx 配置Connection和Upgrade两行缺一不可检查 Nginx 版本是否 ≥ 1.3.13旧版本不支持 WebSocket 代理重启 Nginx 后用curl -i -N -H Connection: Upgrade -H Upgrade: websocket http://localhost/flv?streamtest测试应返回HTTP/1.1 101 Switching Protocols。5.5 现象EasyMedia-ui 页面空白Console 报Uncaught SyntaxError: Unexpected token 原因前端用http-server启动时未加--cors或 Nginx 配置中location /的alias路径末尾少了/导致index.html加载了index.html自身返回 200 HTML 内容而浏览器试图把 HTML 当 JS 解析。解决http-server启动必加--corsNginx 中alias /path/to/emui/;的路径必须以/结尾或改用root /path/to/emui;location / { try_files $uri $uri/ /index.html; }组合更鲁棒。6. 验证与调试从流接入到画面渲染的全链路观测法装完不是终点验证才是。我从不依赖“点一下播放看有没有画面”这种玄学测试而是建立一套分层观测体系每一层都可独立验证、独立报错、独立修复。下面是我的标准验证流程覆盖从底层流接入到最终渲染的 4 个关键断点。6.1 断点一RTSP 源是否可达—— 用 FFmpeg 做原子级探测这是最底层的验证绕过所有中间件直连摄像头。目标确认rtsp://地址、账号密码、端口全部正确且网络可达。# Windows/macOS/Linux 通用命令 ffmpeg -v verbose -i rtsp://admin:123456192.168.1.100:554/stream1 -t 5 -f null --v verbose: 输出详细日志关键看Opening rtsp://...和Successfully opened the file-t 5: 只拉 5 秒避免长时间等待-f null -: 丢弃所有数据只测连通性。✅ 成功标志日志末尾出现frame xxx fpsxx q-1.0 LsizeN/A time00:00:05.00 bitrateN/A且无Connection refused或Authentication Failed。❌ 失败处理若报401 Unauthorized检查密码若报Connection timed out用ping 192.168.1.100和telnet 192.168.1.100 554确认网络与端口。6.2 断点二EMS 是否正常拉流—— 观察日志与 API 响应启动 EMS 后它会主动拉取rtsp_sources.yml中所有流。验证它是否“干活”不看画面看日志和 API。看日志EMS 启动后每 5 秒会打印一条INFO[xxxx] Stream camera01 status: running或connecting/failed。若长期显示connecting说明 RTSP 拉流卡住若显示failed则复制日志中的错误如read tcp: i/o timeout针对性解决。调 API用浏览器或 curl 访问http://localhost:8080/api/streams应返回 JSON[ { name: camera01, url: rtsp://..., status: running, clients: 0 } ]✅status为running且clients字段存在说明 EMS 已成功拉流并准备就绪。❌ 若返回空数组或404检查 EMS 是否启动、端口是否正确、rtsp_sources.yml路径是否对。6.3 断点三WebSocket 数据是否真实推送—— 用 wscat 抓原始 FLV 流这是最关键的中间验证。EasyMedia-ui 的ws-player.js本质就是个 WebSocket 客户端我们用命令行工具wscat模拟它直接接收原始 FLV 数据确认 EMS 真正在“发”。# 先安装 wscatNode.js npm install -g wscat # 连接 EMS 的 WebSocket-FLV 端点 wscat -c ws://localhost:8080/flv?streamcamera01若连接成功终端会显示Connected (press CTRLC to quit)且立即开始刷出大量二进制乱码FLV header 和 tag 数据若连接失败报error: Unexpected server response: 200说明 Nginx 代理配置错误见 5.4若连接后无输出说明 EMS 未对该 stream 拉流检查日志中camera01状态。提示wscat输出的乱码是正常的 FLV 二进制流。你可以重定向到文件wscat -c ws://... test.flv然后用 VLC 播放test.flv若能播放证明 EMS 推流 100% 正常。6.4 断点四EasyMedia-ui 渲染是否正常—— 控制台 Network MSE 缓冲区三联查最后一步回到前端。打开http://localhost:8000输入camera01点击播放。不再只看画面而是打开开发者工具三面板联动Console 面板确认无CONFIG、WebSocket、MSE相关报错关注ws-player.js输出的onopen、onmessage (tag size: xxx)、onaddsourcebuffer日志Network 面板过滤ws确认 WebSocket 连接状态为101 Switching Protocols且有持续的Frame数据流Size 列应不断增长Application 面板 → Frames → Media → Source Buffers展开后能看到videobufferBuffered时间轴应随播放实时延伸若Buffered为空或卡住说明 FLV tag 未正确 append可能是时间戳问题见 5.3。✅ 全部满足且画面流畅无卡顿即为全链路跑通。此时你可以放心将config.js中的wsUrl改为生产环境地址部署上线。从那以后我每次部署 EasyMedia-ui都强制走一遍这四个断点FFmpeg → EMS API → wscat → 前端三面板。少一个心里就不踏实。它不保证 100% 无坑但能把 95% 的“为什么播不了”问题在 5 分钟内定位到具体模块。希望帮到你。本文还有配套的精品资源点击获取