油猴脚本实战：为动漫网站打造Canvas弹幕播放器

1. 从“看番没弹幕”说起这个脚本到底在解决什么问题如果你习惯在B站或者A站追番突然换到某个小众动漫网站第一反应大概率是——怎么这么安静没有弹幕飘过没有“前方高能”预警没有“名场面打卡”连“空降成功”都看不到。画面是那个画面但总觉得少了点灵魂。弹幕这个东西说它是“视频的灵魂”有点夸张但它确实构成了很多人追番体验中不可分割的一部分。问题在于绝大多数动漫网站要么根本没有弹幕系统要么自带的弹幕功能简陋到让人不想用——不能调透明度、不能屏蔽关键词、不能调速度甚至连弹幕池都是空的。油猴脚本Tampermonkey就是在这个缝隙里找到了自己的位置。它本质上是一个浏览器扩展允许你在任意网页上注入自定义的JavaScript代码。换句话说只要你能写代码就能给任何网站“加装”功能。而“动漫网站弹幕播放”这个脚本做的事情就是在那些没有弹幕或者弹幕体验很差的动漫网站上强行塞进去一个功能完整的弹幕播放器。它不依赖网站自身的弹幕系统而是自己维护一套弹幕的发送、接收、渲染和存储逻辑。这个脚本适合谁用三类人。第一类追番量大、经常在多个网站之间切换的深度用户他们需要一个统一的弹幕体验第二类对弹幕有重度依赖的观众没有弹幕就看不下番的那种第三类有前端基础、想自己动手改造观看体验的技术爱好者。如果你属于这三类中的任何一类接下来的内容应该能给你不少参考。我最初接触这个脚本是因为一个很具体的场景某个动漫网站的画质和片源都不错但弹幕系统年久失修发出去的弹幕经常不显示刷新之后又全部消失。忍了大概两周之后我决定自己动手。这篇文章就是把我从零开始搭建这个脚本的完整过程、踩过的坑、以及最终稳定运行的方案整理出来。不是教程式的“第一步第二步”而是把每个决策背后的逻辑讲清楚让你能根据自己的需求做调整。2. 弹幕播放器的核心机制从弹幕生成到屏幕渲染的完整链路2.1 弹幕数据的生命周期要理解这个脚本怎么工作得先搞清楚一条弹幕从“被发送”到“出现在屏幕上”经历了什么。整个过程可以拆成四个阶段生成、传输、存储、渲染。每个阶段都有不同的技术选型和坑点。生成阶段最简单就是用户在输入框里打字按下回车。但这里有个容易被忽略的细节弹幕的元数据。一条完整的弹幕不只是文字内容还包括发送时间相对于视频播放进度的秒数、颜色、字号、位置滚动、顶部、底部、发送者标识。这些信息决定了弹幕在什么时间点、以什么样式出现在屏幕上。很多简易弹幕系统只存文字和时间结果就是所有弹幕都是白色滚动毫无层次感。传输阶段是脚本和服务器之间的通信。如果你的脚本只是本地渲染那不需要传输但弹幕的乐趣在于“看到别人发的”。所以必须有一个后端来收集和分发弹幕。这里的选择很多可以用现成的弹幕API比如某些开源弹幕库提供的公共服务也可以自己搭一个轻量级的后端。我一开始用的是某个公开的弹幕API但后来发现延迟高、丢包严重而且时不时挂掉。最终方案是自己用Node.js写了一个极简的弹幕服务部署在一台低配云服务器上成本每月不到一杯咖啡的钱。存储阶段决定了弹幕能不能“持久化”。如果只存在内存里服务器一重启就全没了。我用的是SQLite轻量、零配置、单文件对于个人项目来说完全够用。每条弹幕存成一行记录字段包括视频ID、时间偏移、内容、颜色、位置、发送时间戳。查询的时候按视频ID和时间偏移建索引读取速度很快。渲染阶段是脚本在浏览器端做的事情。核心逻辑是监听视频的timeupdate事件拿到当前播放时间然后从弹幕池里取出时间偏移在[当前时间-0.5秒, 当前时间0.5秒]范围内的弹幕创建DOM元素用CSS动画让它们从右向左飘过屏幕。听起来简单但实际写起来有一堆细节要处理。2.2 为什么选择Canvas而不是DOM这是我在开发过程中做的第一个重要决策。最初我用的是DOM方案每条弹幕创建一个div用CSStransform做动画。优点是实现简单样式好控制调试方便。但问题很快就暴露了当弹幕密度上来之后比如一秒钟有几十条弹幕同时飘过页面开始明显卡顿帧率从60掉到30甚至更低。原因很简单每个DOM元素都是一个独立的渲染层浏览器要为每个元素计算样式、布局、合成开销随弹幕数量线性增长。Canvas方案则完全不同。整个弹幕层就是一个canvas元素所有弹幕都画在同一张画布上。每一帧只需要清空画布然后遍历当前活跃的弹幕计算它们的位置调用fillText绘制文字。没有DOM操作没有样式计算性能开销几乎只取决于弹幕数量和文字绘制本身。实测下来同样密度的弹幕Canvas方案的帧率能稳定在55-60而DOM方案已经掉到20以下。但Canvas也有代价。文字样式控制不如CSS灵活比如描边、阴影、渐变这些效果需要手动实现。而且Canvas上的文字不能被选中、不能被浏览器搜索、不能响应鼠标事件。不过对于弹幕来说这些“缺点”恰好都不重要——没人需要选中弹幕文字也没人需要点击弹幕。所以这个取舍是值得的。具体实现上我维护了一个activeDanmaku数组每帧遍历这个数组更新每条弹幕的x坐标然后绘制。当弹幕的x坐标超出画布左边界时从数组中移除。新弹幕的加入通过一个队列来管理避免在遍历过程中修改数组。2.3 弹幕碰撞检测让弹幕不重叠的算法弹幕重叠是体验杀手。如果两条弹幕在同一时间、同一轨道上重叠在一起文字会糊成一团完全看不清。所以必须做碰撞检测确保每条新弹幕都能找到一条“空闲”的轨道。我的做法是把屏幕垂直方向分成若干条固定高度的轨道每条轨道的高度等于弹幕字号加上行间距。当一条新弹幕要加入时从第一条轨道开始检查这条轨道上最后一条弹幕的右边界是否已经移出了屏幕右边缘如果是说明这条轨道空闲可以使用。如果不是检查下一条轨道。如果所有轨道都满了有两种策略要么丢弃这条弹幕要么让它稍微延迟一点再出现。我选择的是后者——把弹幕放入等待队列下一帧再尝试。这里有个细节轨道的“占用”状态不是简单的布尔值而是需要记录每条轨道上最后一条弹幕的当前位置和速度。因为弹幕的速度可能不同用户可以选择慢速、中速、快速所以判断条件应该是最后一条弹幕的右边界是否已经小于屏幕宽度。如果小于说明它已经完全进入屏幕新弹幕可以跟在后面。实际代码里我用了一个trackStatus数组每个元素记录该轨道上最后一条弹幕的rightEdge和speed。每次尝试插入新弹幕时遍历这个数组找到第一个满足rightEdge canvasWidth的轨道。如果找不到就把弹幕暂存到pendingQueue里下一帧再试。2.4 弹幕的样式与交互设计弹幕的样式看似简单但要做好用需要考虑不少细节。颜色方面我提供了预设的几种常用颜色白色、红色、黄色、绿色、蓝色、紫色同时也允许用户自定义。字号方面默认是24px但用户可以在设置面板里调整。位置方面支持滚动、顶部固定、底部固定三种模式。交互上最重要的功能是弹幕开关和透明度调节。有些场景下用户只想安静看番一键关闭弹幕就行。透明度调节则是为了在弹幕密集的时候降低干扰同时保留“有人在看”的氛围感。这两个功能我都做成了快捷键D键切换弹幕显示[和]调节透明度。还有一个容易被忽略的功能是弹幕屏蔽。关键词屏蔽、用户屏蔽、正则屏蔽这三个层次覆盖了绝大多数需求。关键词屏蔽就是简单的字符串匹配用户屏蔽需要弹幕携带发送者标识正则屏蔽则是给高级用户用的。我在实现时把这三个层次做成可叠加的优先级从高到低依次是用户屏蔽 正则屏蔽 关键词屏蔽。3. 油猴脚本的工程化实践从单文件到可维护的代码结构3.1 为什么不能把所有代码塞进一个文件油猴脚本的默认形态是一个.user.js文件里面包含元数据块和全部JavaScript代码。对于简单的脚本这样没问题。但这个弹幕播放器的代码量很快就超过了2000行如果全部塞在一个文件里维护起来会非常痛苦。变量命名冲突、函数作用域混乱、修改一个功能要翻半天代码这些都是我实际遇到的问题。我的解决方案是模块化。虽然油猴脚本本身不支持ES Module的import语法但可以通过require指令引入外部脚本文件。我把代码拆成了几个模块danmaku-core.js负责弹幕的渲染和碰撞检测danmaku-api.js负责和后端通信danmaku-ui.js负责设置面板和输入框danmaku-storage.js负责本地存储和配置管理。主脚本只负责初始化和协调这些模块。这样做的好处很明显每个模块的职责单一修改一个模块不会影响其他模块调试的时候可以单独测试某个模块代码复用性也提高了比如danmaku-core.js可以不加修改地用在其他视频网站上。3.2 油猴脚本的元数据块配置元数据块是油猴脚本的“身份证”决定了脚本在哪些网站上运行、需要哪些权限、依赖哪些外部库。这个脚本的元数据块我改了好几版最终稳定下来的配置如下// UserScript // name 动漫网站弹幕播放 // namespace http://your-namespace // version 2.3.1 // description 为任意动漫网站添加弹幕播放功能 // author YourName // match *://*.example-anime-site.com/* // match *://*.another-anime-site.com/* // grant GM_xmlhttpRequest // grant GM_setValue // grant GM_getValue // grant GM_addStyle // connect your-danmaku-api.com // require https://your-cdn.com/danmaku-core.js // require https://your-cdn.com/danmaku-api.js // run-at document-end // /UserScript几个关键点match决定了脚本在哪些域名下生效我一开始用了通配符*://*/*结果发现脚本在所有网站上都会尝试初始化浪费资源还容易出错。后来改成精确匹配几个常用的动漫网站域名问题就解决了。grant声明了脚本需要使用的油猴API权限GM_xmlhttpRequest用于跨域请求弹幕APIGM_setValue和GM_getValue用于持久化用户配置。connect声明了允许跨域请求的域名不写的话GM_xmlhttpRequest会被拦截。run-at document-end确保脚本在DOM加载完成后执行避免找不到视频元素。3.3 视频元素的定位与适配不同动漫网站的视频播放器实现方式千差万别。有的用原生video标签有的用iframe嵌套有的用Flash虽然现在很少了还有的用自定义的播放器组件。脚本要做的第一件事就是找到视频元素然后在其上方叠加一个弹幕画布。对于原生video标签直接document.querySelector(video)就能拿到。但问题是很多网站的视频元素是动态加载的页面初始加载时可能还不存在。所以需要用一个MutationObserver来监听DOM变化一旦发现video元素出现就立即初始化弹幕层。对于iframe嵌套的情况如果视频在跨域的iframe里脚本是无法直接访问的。这时候只能退而求其次在iframe外层做文章或者放弃对该网站的支持。我在实际开发中遇到过一个网站视频在iframe里但iframe的域名和主页面相同这种情况下可以通过iframe.contentDocument访问内部DOM问题就解决了。还有一个坑是视频元素的尺寸变化。有些网站支持全屏、剧场模式、小窗模式视频元素的尺寸会动态改变。弹幕画布必须跟着调整否则会出现弹幕超出画面或者被裁剪的情况。我的做法是用ResizeObserver监听视频元素的尺寸变化一旦变化就重新设置画布的width和height属性并重新计算轨道数量。3.4 配置持久化与用户偏好管理用户配置的持久化看起来简单但要做好用需要考虑不少细节。我用的是GM_setValue和GM_getValue这是油猴脚本提供的跨页面持久化存储方案数据存在浏览器本地不会因为刷新页面而丢失。配置项包括弹幕开关状态、透明度、字号、速度、显示区域全屏/半屏/1/4屏、屏蔽关键词列表、屏蔽用户列表、正则屏蔽规则、弹幕颜色偏好、发送者标识随机生成还是自定义。这些配置在脚本初始化时读取在用户修改时写入。这里有个细节配置的读取和写入是异步的。GM_getValue返回的是一个Promise在新版油猴中所以初始化逻辑需要放在async函数里或者用回调处理。我一开始没注意这一点导致配置还没读取完就开始渲染弹幕结果用户设置的透明度没有生效。后来改成await GM_getValue(...)问题就解决了。另外配置的版本管理也很重要。当脚本升级、配置项增加或改名时旧版本的配置需要做迁移。我的做法是在配置里存一个configVersion字段初始化时检查版本号如果低于当前版本就执行迁移逻辑把旧配置转换成新格式。4. 后端弹幕服务的搭建从零到可用的最小方案4.1 为什么需要一个后端纯前端的弹幕方案不是不可以但体验会差很多。如果弹幕只存在本地那你看到的永远只有自己发的弹幕失去了“和一群人一起看”的感觉。弹幕的核心价值在于共享——你看到别人发的“前方高能”别人看到你发的“名场面”这种跨越时空的互动才是弹幕的灵魂。所以必须有一个后端来收集和分发弹幕。这个后端不需要很复杂核心功能就两个接收弹幕POST和获取弹幕GET。但要做好还需要考虑并发、存储、清理、防滥用等问题。4.2 技术选型Node.js SQLite Express我选Node.js的原因很简单JavaScript全栈前后端用同一种语言心智负担小。Express是最轻量的Web框架几行代码就能起一个服务。SQLite作为存储零配置、单文件、性能足够。整个后端代码不到200行部署在一台1核1G的云服务器上跑了几百个视频的弹幕完全没压力。数据库表结构很简单CREATE TABLE danmaku ( id INTEGER PRIMARY KEY AUTOINCREMENT, video_id TEXT NOT NULL, time_offset REAL NOT NULL, content TEXT NOT NULL, color TEXT DEFAULT #FFFFFF, position TEXT DEFAULT scroll, font_size INTEGER DEFAULT 24, sender_id TEXT, created_at INTEGER DEFAULT (strftime(%s, now)) ); CREATE INDEX idx_video_time ON danmaku(video_id, time_offset);video_id是视频的唯一标识我用的是视频URL的MD5哈希值这样不同网站的视频不会冲突。time_offset是弹幕相对于视频开始的时间偏移单位是秒用浮点数存储。position有三种取值scroll滚动、top顶部固定、bottom底部固定。4.3 API设计简洁但够用后端只暴露两个接口POST /api/danmaku发送弹幕。请求体是JSON包含video_id、time_offset、content、color、position、font_size、sender_id。服务端做基本的校验内容长度不超过100字、时间偏移在合理范围内、发送频率限制然后写入数据库。GET /api/danmaku?video_idxxxstart0end300获取弹幕。返回指定视频、指定时间范围内的所有弹幕。start和end是时间偏移的区间脚本会根据当前播放进度动态请求。这个设计的好处是按需加载。一个视频可能有几千条弹幕一次性全部返回会给客户端和网络都带来压力。按时间区间请求每次只拿当前需要的部分体验更流畅。脚本里维护一个本地缓存已经请求过的时间区间不会重复请求。4.4 防滥用与性能优化公开的弹幕API很容易被滥用。我遇到过有人写脚本批量发送垃圾弹幕也遇到过爬虫疯狂请求导致服务器负载飙升。所以必须做一些基本的防护。发送频率限制是最基本的同一个sender_id在10秒内只能发送一条弹幕1分钟内最多发送10条。这个限制在服务端做用内存里的Map记录每个sender_id的最近发送时间。内容校验也很重要长度限制、敏感词过滤、重复内容检测。重复内容检测的逻辑是如果同一个sender_id在5分钟内发送了完全相同的内容直接拒绝。性能方面SQLite的读写速度对于这个量级完全够用。但如果弹幕量继续增长可以考虑加一层Redis缓存把热门视频的弹幕缓存在内存里。不过对于个人项目来说SQLite已经足够了。5. 实际部署与调试中遇到的典型问题5.1 跨域请求被拦截这是开发过程中遇到的第一个拦路虎。脚本运行在动漫网站的页面上请求弹幕API的域名和当前页面域名不同浏览器的同源策略会直接拦截请求。解决方案是用油猴提供的GM_xmlhttpRequest它不受同源策略限制。但要注意使用GM_xmlhttpRequest需要在元数据块里声明connect列出允许请求的域名。我一开始忘了写connect请求一直失败排查了半天才发现问题。5.2 视频进度跳转时的弹幕同步用户拖动进度条跳转时弹幕必须跟着跳转。如果处理不好会出现弹幕堆积或者弹幕消失的问题。我的做法是监听视频的seeking事件在跳转发生时清空当前活跃的弹幕数组和等待队列然后根据新的播放时间重新请求弹幕数据。这里有个细节跳转后的弹幕请求需要有一个短暂的延迟大概200毫秒因为seeking事件触发时视频的currentTime可能还没有更新到最终位置。5.3 全屏模式下的弹幕层适配全屏模式下视频元素会占据整个屏幕弹幕画布也需要跟着全屏。但浏览器的全屏API有个特点全屏的是某个特定的元素而不是整个页面。如果弹幕画布不是全屏元素的子元素它就不会显示在全屏画面上。解决方案是把弹幕画布作为视频元素的兄弟节点并且在全屏时把弹幕画布也加入到全屏元素中。具体做法是监听fullscreenchange事件在全屏时把弹幕画布移动到全屏元素的容器里退出全屏时再移回来。5.4 移动端浏览器的兼容性虽然油猴脚本主要在桌面浏览器上使用但有些用户也会在移动端浏览器比如Kiwi Browser上安装油猴。移动端的触摸事件、屏幕尺寸、性能都和桌面端不同。我遇到的主要问题是移动端的requestAnimationFrame在页面不可见时会暂停导致弹幕停止渲染。解决方案是监听visibilitychange事件在页面重新可见时恢复渲染循环。另外移动端的屏幕宽度较小轨道数量需要动态调整否则弹幕会过于拥挤。6. 一些值得分享的实操心得弹幕的发送者标识我建议用随机生成的ID而不是用户的真实身份。这样既保护了隐私又避免了用户之间的互相攻击。随机ID存在本地用户可以在设置里重置。弹幕的透明度调节我建议做成快捷键而不是滑块。滑块需要鼠标操作会打断观看体验。快捷键[和]可以单手操作不影响看番。弹幕的屏蔽功能我建议默认开启一些常见的垃圾弹幕关键词比如“打卡”、“签到”、“第一”这类。这些弹幕没有信息量只会干扰观看。后端的弹幕清理我建议设置一个定时任务定期删除超过一定时间比如30天的弹幕。否则数据库会越来越大查询速度也会下降。弹幕的渲染我建议用requestAnimationFrame而不是setInterval。requestAnimationFrame会和浏览器的刷新率同步渲染更流畅而且在页面不可见时会自动暂停节省资源。最后如果你也想自己动手做类似的东西我的建议是从最小的可用版本开始。先实现最基本的弹幕发送和渲染跑通了再逐步加功能。不要一开始就想着做得多完美很多细节是在实际使用中才发现需要处理的。我第一版脚本只有不到300行代码功能简陋但能用。后来在不断使用的过程中才慢慢加上了碰撞检测、屏蔽、配置持久化这些功能。这个过程本身就是最好的学习方式。