深入浅出jessibuca的Emitter：事件总线与播放器实战

先抛一个场景：你在用jessibuca做实时播放器，页面里要监听播放器的加载成功、视频首帧出现、播放出错这些状态。如果你去看官方文档，会发现一大半的API都在讨论on、off、emit这几个方法。很多新手会直接跳过这块，觉得“反正照着示例把on抄下来就能用”，结果一旦遇到需要自定义事件、跨组件通信、或者排查“为什么回调没触发”这类问题，就彻底卡住了。

这个系列第二篇，我就专门把Emitter类拎出来讲透。它不光是jessibuca播放器内部的消息中枢，也是你与播放器交互时最核心的通道。搞懂它，你就搞懂了jessibuca一大半的API设计逻辑。

1. 为什么非要有Emitter：播放器里的“事件总线”思维

先说个最朴素的问题：jessibuca为什么要把事件机制单独抽成一个类？ 直接写回调函数不好吗？

如果你用过一些老旧的js库，它们确实这么干：player.onLoad = function(){}，一个事件一个属性，简单粗暴。但实际开发中这种模式很快会失控——比如我需要同时监听加载进度、渲染状态、网络波动、解码异常，十几个事件全挂成属性，代码会变成一团乱麻，而且没法支持“同一个事件挂多个回调”。

Emitter做的事情，本质上就是给你一张“事件登记表”。你可以在这张表上登记很多个函数，等某个时机到了，它统一喊一嗓子，所有登记过的函数依次执行。这就是业界常说的观察者模式，或者更接地气一点的叫法：发布-订阅模式。

jessibuca内部几乎所有状态变化，都是通过这个模式往外广播的。播放器解码出第一帧画面、缓冲区出现卡顿、连接断开重连，全部走Emitter。所以你在开发中经常看到的jessibuca.on('timeUpdate', callback)、jessibuca.on('error', callback)，本质上就是在向Emitter这张表里登记函数。

这个设计最大的一个好处是解耦。播放器内部不用关心你外部有多少个地方在等它的状态，它只管实现完一个功能，就emit一个信号出去；你外部也完全不用知道播放器内部逻辑，只需要订阅感兴趣的事件就行。两边各干各的，代码清晰、好维护，这也是几乎所有成熟播放器共同的选择。

2. Emitter类核心API拆解：on、off、emit一个都不能少

在jessibuca的源码里，Emitter类其实就几个方法，但每个方法的细节都很值得抠。

2.1 on：注册事件监听，注意重复绑定问题

on(eventName, callback)用于注册事件监听。这里有第一个容易踩坑的点：同一个事件、同一个回调函数，你绑定两次，它就会执行两次。

看一眼内部实现（简化版）：

javascript复制on(eventName, callback) {
    if (!this._events[eventName]) {
        this._events[eventName] = [];
    }
    this._events[eventName].push(callback);
}

这就是个数组push操作，它根本不管你是不是重复的。所以如果你在created里绑了一次，又在mounted里绑了一次，等事件触发时回调就会跑两遍。排查问题的时候先想想：是不是同一个回调绑重复了。

2.2 once：只执行一次的监听，适合首帧、首屏事件

once(eventName, callback)和on很像，但它只触发一次，触发完自动解绑。看实现：

javascript复制once(eventName, callback) {
    const wrapper = (...args) => {
        this.off(eventName, wrapper);
        callback.apply(this, args);
    };
    this.on(eventName, wrapper);
}

注意这里的关键细节：它把callback包了一层wrapper，然后向事件表里注册的是wrapper，而不是你原来的callback。 这一点很重要，因为如果你之后想手动off掉这个监听，你必须传入同一个wrapper，但你根本拿不到wrapper，所以你没办法在触发前用off取消它。

这会带来一个实际问题：比如你once('play', cb)，结果play事件一直没触发，播放器销毁了，这个监听还挂在事件表里——不过库内部一般会在destroy时统一清空，所以你不用太慌，但要意识到once的本质是“触发后清理”，不是“不触发也自动清理”。

2.3 off：解绑事件监听，精确匹配还是全部清空

off(eventName, callback)用于移除监听。如果没有传callback，它会把该事件名下的所有监听全部清空；如果传了，只移除匹配的那一个。

javascript复制off(eventName, callback) {
    if (!this._events[eventName]) return;
    if (!callback) {
        delete this._events[eventName];
        return;
    }
    this._events[eventName] = this._events[eventName].filter(item => item !== callback);
}

这里就有个和once联动的大坑了：如果你用once('play', handlePlay)注册了监听，之后想用off('play', handlePlay)手动取消，你会发现取消不掉。因为事件表里存的是wrapper，不是handlePlay，filter匹配不到。想取消？没门，只能等它触发或者播放器销毁。

所以我的建议是：如果你预判某个事件可能需要提前取消监听，就老老实实用on，别用once。 如果确实想用once又想能取消，得自己封装一层，或者干脆用on然后在回调里手动off。

2.4 emit：触发事件，同步执行还是异步执行

emit(eventName, ...args)负责触发事件。它会把事件名下所有回调按顺序执行，并把参数传进去。

javascript复制emit(eventName, ...args) {
    if (!this._events[eventName]) return;
    this._events[eventName].forEach(cb => {
        cb.apply(this, args);
    });
}

这里值得注意的一点是：Emitter默认是同步触发的。 也就是说，emit一调用，所有回调立刻执行，等它们全部跑完，emit才返回。

这在实际开发中会带来一个体验问题：如果你的回调里放了很重的逻辑，比如解析一段数据、渲染一个图表，那么播放器在emit时就会被卡住，表现就是页面掉帧、卡顿。如果你遇到这种情况，考虑在回调里用setTimeout、requestAnimationFrame或Promise.resolve().then做异步化，把重活挪出同步执行链。

2.5 一个值得注意的绑定细节：回调里的this指向

看上面的实现，cb.apply(this, args)，这个this指向的是Emitter实例本身，而不是你传入回调时所在的那个对象。很多人在回调里用this访问自己的Vue组件或React组件，发现是undefined或者指向播放器，就是这个原因。

解决办法很简单：回调函数用箭头函数定义，或者在合适的地方提前bind。

3. Emitter类在jessibuca中到底干了什么：从源码到播放器事件

前面讲的是Emitter的通用能力，现在把它放回jessibuca这个大背景里。jessibuca之所以把Emitter单独抽出来，是因为播放器内部有好几个地方要用到事件机制，而不仅仅是给外部开发者用。

3.1 播放器内部事件流：从解码到通知

jessibuca的播放流程大概长这样：拉流 -> 解封装 -> 解码 -> 渲染。每一步都可能产生状态变化。比如：

• 开始拉流时，需要告诉外部“我在连接了”
• 拿到视频数据、解出第一帧时，需要告诉外部“准备出画了”
• 网络波动导致缓冲时，需要告诉外部“卡一下”
• 出错时，需要告诉外部“我挂了”

如果没有Emitter，这些状态就只能靠外部轮询或者回调嵌套，代码会非常痛苦。有了Emitter，播放器内部只要在对应位置emit一下，外部就能收到通知，各干各的。

我特意去看过jessibuca的源码，播放器内部到处都是this.emit('xxx', data)这样的调用。它就是靠Emitter这把总线，把内部所有模块串起来的。

3.2 播放器外部：给使用者的统一事件接口

对使用jessibuca的开发者来说，Emitter主要体现在两个地方。

第一个是播放器实例上。jessibuca创建的实例对象本身就带on、off、emit方法，你可以直接对播放器实例注册事件监听，比如：

javascript复制const player = new Jessibuca({
    container: document.getElementById('container'),
    url: '你的流地址'
});

player.on('load', () => {
    console.log('播放器加载完成');
});

player.on('play', () => {
    console.log('开始播放');
});

player.on('error', (error) => {
    console.error('播放出错', error);
});

第二种是让你自定义事件。如果你在jessibuca的基础上封装了自己的业务组件，你可以通过播放器实例的emit方法向外广播自己的业务事件，让其他模块监听。这个在复杂的业务系统里尤其好用——一个负责播放的模块，可以把“摄像头离线”“视频卡顿超过阈值”这类业务语义的事件emit出去，其他模块只要on一下，就完成了解耦。

3.3 jessibuca中常用事件速查表

我把jessibuca开发中最常用的事件整理成一张表，方便你对照使用：

这张表不是官方的，是我基于实际使用总结的常用部分，更完整的事件列表建议直接看官方文档的最新版本。但核心思路是一样的：每个事件都是一个时机，你只需要在正确的时机干正确的事。

3.4 传参提权：每次emit都携带业务数据

留意emit(eventName, ...args)的参数设计，事件触发时可以带任意多个参数。这意味着你完全可以把数据“塞”进事件里，回调里直接拿到。

举个例子，我要监听jessibuca的stats事件获取实时带宽和帧率：

javascript复制player.on('stats', (stats) => {
    console.log('实时码率', stats.bps);
    console.log('实时帧率', stats.fps);
});

这比在回调里再去调API问播放器要数据要高效得多。因为事件回调执行时，数据已经准备好了，直接消费就行。

4. 完整实操：从零实现一个极简Emitter并在业务中使用

知道原理还不够，我建议你亲手实现一个精简版，这样以后排查问题会顺手很多。下面这个实现大概五十行，涵盖了on、off、once、emit的核心逻辑，你可以直接跑起来看效果。

javascript复制class Emitter {
    constructor() {
        this._events = Object.create(null);
    }

    on(eventName, callback) {
        if (!this._events[eventName]) {
            this._events[eventName] = [];
        }
        this._events[eventName].push(callback);
        return this;
    }

    once(eventName, callback) {
        const wrapper = (...args) => {
            this.off(eventName, wrapper);
            callback.apply(this, args);
        };
        this.on(eventName, wrapper);
        return this;
    }

    off(eventName, callback) {
        if (!this._events[eventName]) return this;
        if (!callback) {
            delete this._events[eventName];
            return this;
        }
        this._events[eventName] = this._events[eventName].filter(
            item => item !== callback
        );
        return this;
    }

    emit(eventName, ...args) {
        if (!this._events[eventName]) return this;
        this._events[eventName].forEach(cb => {
            cb.apply(this, args);
        });
        return this;
    }
}

下面是测试代码，覆盖几个典型场景：

javascript复制const bus = new Emitter();

const handlePlay = (msg) => {
    console.log('play 事件触发了：', msg);
};

// 1. 普通注册
bus.on('play', handlePlay);
bus.emit('play', '第一次触发');
// 输出：play 事件触发了： 第一次触发

// 2. once注册，只能触发一次
bus.once('load', (info) => {
    console.log('load 事件（只触发一次）：', info);
});
bus.emit('load', 'aaaa');
bus.emit('load', 'bbbb');
// 只会输出一次 load

// 3. off解绑
bus.off('play', handlePlay);
bus.emit('play', '这次不会再触发');
// 无输出，说明已经解绑成功

跑一遍这个测试，你对Emitter的行为模式就有肌肉记忆了。之后再看到jessibuca源码里的各种emit，就不会觉得陌生，反而能迅速判断：哦，这里是在广播状态变化，那里是在带数据。

5. 实战场景：把Emitter和jessibuca播放器结合起来

现在我们把理论落在真实项目里。假设你正在用Vue3写一个监控大屏，页面上有多个摄像头画面，每个画面都是一个jessibuca播放器实例。这一节我带你过一遍完整流程，从安装到事件监听，再到一些进阶的处理技巧。

5.1 安装与引入

jessibuca本身是一个npm包，用起来很简单：

bash复制npm install jessibuca

然后在需要的组件里引入：

javascript复制import Jessibuca from 'jessibuca';
import 'jessibuca/assets/css/jessibuca.css';

如果你不用npm，也可以直接用官方提供的静态资源版本，script标签引入即可。不过npm包方式更利于打包和版本管理，推荐这种方式。

5.2 创建播放器实例并挂载事件

创建播放器实例时，容器必须存在。所以如果你在Vue里，通常在onMounted之后创建：

javascript复制onMounted(() => {
    player = new Jessibuca({
        container: document.getElementById('player-container'),
        url: '你的播放地址',
        videoBuffer: 1,
        isResize: true,
        text: {
            loading: '正在加载视频...',
        }
    });

    // 监听核心事件
    player.on('load', () => {
        console.log('播放器加载完成');
    });

    player.on('start', () => {
        console.log('首帧渲染，视频开始播放');
        loadingStatus.value = 'playing';
    });

    player.on('error', (error) => {
        console.error('播放出错', error);
        loadingStatus.value = 'error';
    });
});

看到没有，你只需要在合适的事件里更新UI状态，播放器根本不需要知道你的UI长什么样，这就是前面说的解耦。

5.3 常见场景：监听首帧出画、错误处理、销毁清理

首帧出画是监控场景最关心的指标之一，用户打开页面最想立刻看到画面。对应的事件是start，表示已经开始解码并渲染出第一帧。

javascript复制player.on('start', () => {
    // 首帧出现，隐藏loading，显示画面
    this.loadingVisible = false;
    this.firstFrameArrived = true;
});

错误处理上，error事件只是告诉你出错了，你通常还需要区分错误类型。jessibuca的错误对象里会带错误码，你可以根据自己的业务做差异化处理，比如网络错误自动重连、认证失败跳转登录等。

销毁清理这块非常关键。Vue组件卸载时，如果不销毁播放器，会留下定时器、解码线程、网络连接，轻则内存泄漏，重则浏览器卡死。在onUnmounted里做清理：

javascript复制onUnmounted(() => {
    if (player) {
        const consoleFlag = player.isPlaying();
        if (consoleFlag) {
            player.destroy();
        }
        player = null;
    }
});

5.4 事件风暴场景：高频事件如何优化性能

jessibuca的timeUpdate和stats这类事件触发频率很高，尤其是timeUpdate，播放过程中每秒可能会触发很多次。如果你在回调里做重活，比如直接改DOM、写本地存储、调用接口上报，会对性能产生明显影响。

我的处理思路是加一层“节流”或“缓冲”。比如收集统计信息，每隔几秒统一上报一次，而不是每次事件都上报：

javascript复制let statsCache = [];
player.on('stats', (stats) => {
    statsCache.push(stats);
    // 简单节流：每2秒处理一次
    if (statsCache.length === 1) {
        setTimeout(() => {
            // 把缓存的数据做批量处理
            processStats(statsCache);
            statsCache = [];
        }, 2000);
    }
});

如果你不需要那么高频的数据，完全可以在回调里判断一下时间戳，达到阈值才处理。原则就一条：高频事件回调里尽量做轻量操作，把耗时操作延后或合并。

5.5 结合业务：自定义业务事件广播

当你在播放器基础上封装业务组件时，Emitter的自定义事件能力就非常有用了。比如我封装了一个CameraPlayer组件，对内管理播放器实例，对外只暴露业务事件：

javascript复制class CameraPlayer {
    constructor(container, url) {
        this.player = new Jessibuca({ container, url });
        // 监听底层播放器事件，翻译成业务事件
        this.player.on('error', (error) => {
            this.emit('cameraError', { code: error.code, message: error.message });
        });
    }

    on(eventName, callback) {
        this.player.on(eventName, callback);
    }

    off(eventName, callback) {
        this.player.off(eventName, callback);
    }

    emit(eventName, data) {
        this.player.emit(eventName, data);
    }
}

这样，业务侧只需要关心cameraError这种业务事件，不需要理解jessibuca底层的错误码体系。当我需要扩展播放器能力时，只需要在CameraPlayer内部做一次翻译、转义，外部毫无感知。

6. 常见问题与排查技巧实录：基于真实项目踩坑总结

这部分是我自己在项目里真实遇到、并且花了不少时间才定位的问题，整理出来希望能帮你少走弯路。

6.1 回调不触发？先查off和once

最常见的排查方向就三步：

1. 确认事件名拼写正确。play和Player、load和onload，看起来差不多，实际完全不是一回事。
2. 确认是不是被off解绑了。有些代码在某个时机（比如created）把回调挂了，但另一个逻辑把它off了。
3. 确认是不是用了once且已经触发过一次。once触发第二次本来就不会再执行，这不是bug，是特性。

6.2 回调执行了两次？多半是重复绑定

我之前在Vue项目里遇到过一个奇葩问题：同一个error监听回调，页面报错一次，却弹了两次提示。排查下来发现是onMounted和watch里面各绑了一次。

其实这种问题看代码就能预防：把事件绑定收敛到一个函数里，保证每个事件名只被绑定一次。 如果你真的需要多个地方监听同一个事件，那也是用“一个监听回调内部再分发”的思路，而不是多次on。

6.3 播放器销毁后事件还在跑？做好全局清理

有些同学在destroy播放器之后，仍然用之前注册的回调去操作已经销毁的DOM，结果控制台报一堆错。jessibuca在destroy时会清掉内部大部分监听，但你自己用player.on注册的回调，以及你自己保存在外层变量里的闭包引用，jessibuca管不到。

所以最佳实践是：播放器销毁时，把你注册的事件都解绑一遍，或者直接放弃对播放器实例的所有引用，让它能够被垃圾回收。 尤其要注意定时器里的引用，那是最隐蔽的内存泄漏来源。

6.4 组件卸载但音频还在响？代码里没销毁事件绑定

有一个真实的场景：你在组件里注册了player.on('play', handlePlay)，后来组件卸载了，你以为播放器销毁了事件也没了，但其实如果你忘了把播放器实例设为null，并且其他地方还保留着对播放器实例的引用，那么播放器内部可能还在跑，音频也可能还在响。

解决方式很直接：组件卸载时把player.destroy()执行，并把变量置null。如果为了保险，可以在onUnmounted里再调用一次player.off()清掉所有事件，双保险。

7. 关于性能优化和代码组织的一些补充经验

最后聊几个我摸索出来的小习惯，不算标准答案，但实测下来对代码维护性很有帮助。

第一，事件名统一用字符串常量或枚举。 别在业务代码里到处写魔法字符串'play'、'timeUpdate'，一旦拼错，排查成本很高。我习惯在项目里建一个eventMap.js，集中导出所有用得到的事件名，既方便查阅，又能利用IDE的自动补全。

第二，回调函数命名要语义化。 别全写匿名箭头函数。虽然匿名函数写起来快，但出错时堆栈信息基本没用。如果回调里出了异常，你看到的报错是at Anonymous function，根本定位不了哪里出了问题。给回调起个名字，报错时一眼就能看出来是哪个监听出的问题。

第三，事件回调里的异常必须捕获。 如果某个监听回调抛异常，按Emiiter的实现，异常会冒泡到emit调用处。而此时emit正被播放器内部调用，异常可能会打断播放器的正常逻辑，甚至让后续事件监听都执行不了。所以我在回调里都会加一层try-catch，或者至少把不确定的代码用Promise包一层异步化，避免影响主流程。

javascript复制player.on('stats', (stats) => {
    try {
        // 业务处理
        this.updateStatsUI(stats);
    } catch (e) {
        console.error('stats回调处理失败', e);
    }
});

第四点，多个播放器实例共享一套Emitter？不要。 每个播放器实例都有自己独立的事件系统，这本身就是设计好的隔离。如果多个播放器要共享业务状态，应该用外部的状态管理（比如Pinia），而不是试图把播放器的事件串起来。

8. 从Emitter到jessibuca的更深一层：事件驱动的播放器设计

理解Emitter之后，你会慢慢发现jessibuca整个库的设计哲学都建立在事件驱动上。你不需要关心播放器内部的解码线程、缓冲策略、渲染管线，你只需要对外部状态做出响应，这是非常适合直播播放场景的架构。

举个更具体的例子。监控墙场景里，多路画面同时播放，某一帧特别卡。基于事件驱动，你可以在stats事件里拿到每路画面的实时帧率，如果低于阈值就自动触发重连，不需要手动轮询，也不需要侵入播放器内部。这就是Emitter带给你的杠杆，它让你能够站在播放器外面，却像站在里面一样掌控局面。

还有一点我觉得值得指出：事件驱动架构让测试变得容易。 你可以在不真连摄像头的情况下，手动emit出各种事件，模拟网络波动、模拟错误码，然后验证你的UI是否正确反应。这比真实环境下的反复断网测试稳定得多。

我个人在实际项目里试过：用一个自定义事件源，模拟摄像头掉线、重连、断流，把整个监控大屏的异常处理流程全部跑通，再切换到真实环境，基本一次通过。这个调试思路希望你也能用上。

如果你已经理解了Emitter的API和工作机制，下一篇可以聊聊jessibuca的播放流程中，各个事件按下什么顺序触发、如何优雅地处理重连和恢复。