BewlyCat 浏览器拓展完全指南：基于 BewlyBewly 的 B 站体验增强、功能清单与本地构建-平芜编程栈

前端

【免费下载链接】BewlyCat

BewlyCat——基于BewlyBewly开发的Bilibili拓展

项目地址：https://gitcode.com/gh_mirrors/be/BewlyCat

BewlyCat 是一个面向 Bilibili 官方网站的浏览器拓展，脱胎于开源项目 BewlyBewly，在保留原项目能力的基础上扩充了十余项新功能、精简了打包体积，并已在 Chrome、Edge、Firefox 三家应用商店上线。本文以仓库根目录的 README.md 为主线，结合 Manifest 定义、package.json 与音量均衡等核心模块源码，系统梳理它的功能异同、安装方式与本地构建流程，读完即可完成从下载安装到自行编译的全过程。

项目定位与设计原则

BewlyCat 的定位非常克制：“只需对您的 Bilibili 主页进行一些小更改即可。”它是一款纯网页体验增强工具，只优化 B 站官方网站的使用体验，因此在 README.md 中明确声明了几条硬性边界：

插件及其 Fork 代码禁止以任何形式的客户端封装，不做“壳”化改造；
项目面向作者个人使用习惯调整，但欢迎功能建议与 Bug 反馈；
浏览器拓展商店的上架审核是并行提交的，实际更新速度取决于各商店的审核节奏，不应在 issue 中催促审核；
不打包 Safari、不做大量 Safari-only 适配，如需可自行打包；
本项目基于 MIT 许可在原项目 BewlyBewly 之上开发，并已与原项目作者取得授权（包括上架 Chrome 应用商店等权利）。

此外，README 中有一条面向搜索可达性的说明：为了让项目能在 GitHub 中被直接搜索到，BewlyCat 脱离 BewlyBewly 的 Fork 网络成为独立项目，但基于 BewlyBewly 的本质不变，也不会移除历史贡献者和原项目信息。这一点在仓库目录结构中同样可见：src/下保留了原项目的顶栏、卡片、内容脚本等组件体系。

[!CAUTION] README 同时提醒：B 站于 2026 年 1 月调整了首页推荐 API，请更新至1.5.6及以上版本以适配新的首页推荐、排行榜和分区。当前仓库 package.json 中的版本号为1.8.0，已包含该适配。

与 BewlyBewly 的主要功能异同

新增功能清单

README 列出了 12 项新增功能，逐条解读如下：

视频卡片、顶栏链接后台打开：点击视频卡片或顶栏链接时在后台标签页打开，不打断当前浏览流。
默认播放器样式设置：当播放器样式为“默认”和“宽屏”时，页面会自动滚动到弹幕框与底部平齐。
用户面板大会员权益领取入口：在用户面板中提供大会员权益的领取入口。
首页推荐前进/后退：为首页推荐流增加前进与后退能力，便于回看被划过的内容。
合集播放自动关闭：需要在设置里开启，方便挂机播放合集时听歌。
Web 模式推荐过滤：按点赞/播放比例过滤视频，同样需要在设置中开启。
自定义快捷键：参考Extension for Bilibili Player插件的快捷键，支持其中大部分功能的自定义快捷键。
记住倍速比例：开启后会记住上次使用的播放倍速。
合集视频随机播放：支持合集内视频随机播放。
视频详情页稍后再看外置：将稍后再看功能从内嵌改为外置呈现。
自定义暗色基准色：开启后暗黑模式的显示会随基准色调整。
合集视频保持默认播放模式：合集播放时维持默认播放模式。
局部音量均衡：在“设置 → Bilibili → 播放器 → 音量均衡”启用，平衡不同视频之间的音量，并通过播放器组件关闭原生均衡，支持目标响度、强度调整及运行状态显示，详见仓库内的算法与资源管理。

其中第 13 项“局部音量均衡”是当前仓库中实现最深入、文档最完整的特性，下文会结合源码单独展开。

删除功能与取舍逻辑

删除原插件的广东话翻译：该翻译现由 BewlyBewly 插件原作者维护，缺少翻译时默认显示英文翻译结果。
删除内置字体：打包体积从14.4M缩减到600K。
删除旧版顶栏以降低开发成本，并重构原项目顶栏组件（功能无差异）。
删除部分影响功能正常使用的动画（如抽屉打开/关闭的动画）。

这一组“删除”体现了明确的工程取舍：用体积、动画和重复维护成本的削减，换取更轻量、更稳定的体验。

安装指南

在线安装（应用商店）

商店	说明
Chrome 应用商店	正式上架，搜索`BewlyCat`安装
Edge 应用商店	已上架，审核周期不定
Firefox 应用商店	已上线（`1.0.2`版本已修复抽屉问题）

[!CAUTION] 各商店审核可能存在延迟：Chrome 一般晚 30 分钟至 15 天，Edge 一般晚 3 至 30 天，Firefox 一般晚 1 至 30 分钟。商店的异常行为由商店导致，不必在 issue 中催促。

本地安装（Edge 和 Chrome，推荐方式）

从 Releases 下载最新的extension.zip；
在 Edge 中打开edge://extensions，或在 Chrome 中打开chrome://extensions；
直接将下载的extension.zip文件拖放到浏览器窗口中即可完成安装。

本地安装（开发者模式加载解压目录）

Edge：

下载extension.zip并解压；
地址栏输入edge://extensions/回车；
打开「开发者模式」并点击「加载已解压的拓展程序」；
选择解压后的扩展文件夹。

Chrome 操作完全一致，仅需将地址换成chrome://extensions/。

本地安装（最新开发版）

如果需要体验最新代码，可使用 CI 自动构建产物，或从 Releases 下载稳定版。开发版用于跟进最新改动，稳定版用于日常使用。

从源码构建与开发调试

构建与贡献流程的完整说明见仓库内的贡献指南。本项目基于 Vite 构建，前置环境为 Node.js 与 pnpm，推荐使用 Visual Studio Code 开发。

开发调试（Chrome / Edge）

# 安装依赖 pnpm install # 创建一个用于存储登录状态的扩展程序文件夹 mkdir chromium-web-ext-profile # 运行项目（开发模式，带热重载） pnpm dev # 自动打开一个新的 Chrome 窗口并打开 Bilibili 网站 pnpm start:chromium

每次修改扩展程序都会自动重新加载，刷新网页即可查看更改。另一种方式是只运行pnpm dev，然后在chrome://extensions/（或edge://extensions/）中开启「开发者模式」，通过「加载已解压的拓展程序」加载生成的extension/文件夹；修改后点击 Reload Extensions 按钮并刷新页面以应用更改。

构建（Chrome / Edge）

pnpm build

产物打包到extension文件夹。pnpm脚本链可以在 package.json 中看到完整定义：build依次执行clear → build:prepare → build:js → build:inject → build:bg，分别对应 scripts/prepare.ts 的准备步骤、vite.config.content.ts 的内容脚本构建、vite.config.inject.ts 的注入脚本构建，以及tsup的后台脚本构建。

开发调试（Firefox）

pnpm install mkdir firefox-web-ext-profile pnpm dev-firefox pnpm start:firefox

第二种方式：运行pnpm dev-firefox后，在 Firefox 中输入about:addons，进入 Extensions → Debug Add-ons，加载生成的extension-firefox/文件夹。

构建（Firefox）

pnpm build-firefox

产物打包到extension-firefox文件夹。若需一键产出全部渠道产物，可运行pnpm build-pack（build + build-firefox + pack:zip + pack:zip-firefox + pack:zip-firefox-sources）。项目同时保留了build-safari与convert-safari脚本，说明 Safari 支持依赖自行打包而非官方维护。

Manifest 与权限的源码级细节

拓展的清单文件由 src/manifest.ts 动态生成，值得关注的实现事实：

Manifest V3，名称取自package.json的displayName，开发模式自动追加Dev后缀；
后台脚本按浏览器分化：Firefox/Safari 使用background.scripts（Firefox 为持久化脚本），Chromium 系使用service_worker+type: module；
权限集：storage、declarativeNetRequest、cookies，Chromium 额外申请scripting，Firefox 额外申请webRequest/webRequestBlocking；
host_permissions限定为*://*.bilibili.com/*与*://*.hdslb.com/*，即只作用于 B 站域；
内容脚本在document_start、all_frames注入，其中注入脚本以world: 'MAIN'运行于页面主世界，用于在原生播放器接管媒体元素之前完成音频处理（见下文音量均衡）；
declarative_net_request规则集加载自 assets/rules.json。

内容脚本的匹配域名定义在 src/constants/contentScript.ts，覆盖www.bilibili.com、search.bilibili.com、space.bilibili.com、passport.bilibili.com等 10 个 B 站域，并显式排除/match/game*与/toy*路径。

深度解析：局部音量均衡的实现原理

“局部音量均衡”是 README 明确指向独立文档的能力，其算法与资源管理说明见 docs/local-loudness.md，源码实现位于 src/inject/audio/localLoudness.ts（AudioWorklet 处理器源码见同目录 localLoudnessProcessor.js，以?raw方式内联进注入脚本）。此处结合 README、文档与源码，把这条特性链路讲透。

入口与参数

入口：设置 → Bilibili → 播放器 → 音量均衡；
设置面板定义在 src/components/Settings/BilibiliFeaturesEnhancement/VolumeBalance/VolumeBalance.vue，包含四个可调项：
- 启用开关（settings.localLoudnessEnabled），默认关闭；
- 目标响度（settings.localLoudnessTarget），滑杆范围-24 ~ -14 LUFS，默认-18 LUFS；
- 强度（settings.localLoudnessStrength），滑杆范围40% ~ 100%，默认75%；
- 显示播放器按钮（settings.showLocalLoudnessButton），隐藏按钮不影响均衡本身是否生效。

文档推荐从-18 LUFS、75% 强度开始尝试。

与原生均衡的协作

启用时，拓展通过 B 站「设置 → 更多播放设置 → 音量均衡 → 关闭」调用 B 站自己的 UI 处理来关闭原生均衡，而不直接修改网站存储或私有 player 对象。源码中disableNative()会点击原生设置按钮、more面板并点选input[value="0"]的关闭项，借此让 B 站自身的持久化与音频图变更逻辑生效。在插件启用期间，文档级click监听会拦截用户再次开启原生均衡的操作，避免两套增益同时作用。关闭插件功能后原生均衡保持关闭；如需重新开启原生音效，应先关闭本功能并刷新页面——因为浏览器不提供释放媒体元素音源所有权的接口，接管是不可逆的。

算法要点

不依赖 B 站返回的整段响度数据，而是由 AudioWorklet 音频线程执行双声道 K-weighting 测量，使用 400 ms 与 3 s 两个滑动窗口，每 100 ms 更新一次控制目标；
采用 BS.1770 的声道能量与 K-weighting 计算方式，文档明确它是局部自动增益，不声称是完整的 EBU R128 节目响度归一化；
增益策略：目标误差按强度折减，最大提升 6 dB、最大降低 18 dB；1 dB 死区减少抖动；下降速率最多 8 dB/s、回升最多 1.5 dB/s；低于-50 LUFS时冻结增益，避免对静音或底噪持续提升；
独立的5 ms 前瞻采样峰值限制器控制突发大声，输出采样峰值不超过-1 dBFS，释放时间 80 ms；它不是过采样真峰值限制器，因此不保证编码后的 dBTP；
测量会补偿媒体音量（用户手动调音量不会被自动增益抵消），静音、暂停、拖动进度时停止测量，换源或拖动进度会清空统计与延迟缓冲。

音源接管与生命周期

注入脚本在document_start阶段（早于原生播放器捕获媒体元素）就通过弱引用映射记录原生创建的媒体音源。接管时把 Worklet 节点插入音源已有输出连接中；关闭时还原连接，但从不关闭原生 AudioContext。对于自己接管的元素，多个元素共享一个 AudioContext，关闭功能后保留最小原声旁路，不强行关闭导致失声。

每次绑定只有一个 Worklet 和一个 AbortController，解绑时恢复旁路、断开处理节点、发送dispose、关闭 MessagePort、清空事件回调并撤销媒体事件监听；
响度窗口、延迟音频、单调队列均使用固定长度类型数组，不存在随播放时长增长的音频缓存；
模块按 AudioContext 弱缓存，Blob URL 在addModule成功或失败后均释放；
异步加载使用代次检查（generation），关闭功能、换视频或pagehide后不再绑定过期任务；
自有音源仅在元素仍位于 DOM 时保持强引用，文档级 MutationObserver 负责在元素移除/重插时恢复必要旁路；
无自有音源连接时暂停自有上下文，页面真正退出时关闭自有上下文并撤销文档监听与原型补丁；
处理失败自动切回原声；不支持或无法确认跨域安全性的音源不接管；若其他拓展先占用了音源，可能需要刷新或停用冲突音效。

播放器控制条上的音量均衡按钮由 src/contentScripts/localLoudnessControl.ts 负责挂载（对应组件 src/components/PlayerLoudnessControl.vue）：它观察播放器控制条结构，在音量图标后插入按钮，悬停可调节开关、目标响度与强度，并显示当前视频运行状态与最近 60 秒的均衡增益曲线（这是实际增益遥测而非原始音频波形），曲线最多保存 61 个采样点；换源、拖动进度或切换功能时清空。该模块在live.bilibili.com不初始化，监听器、观察器与发现重试会在页面隐藏、离页时被清理。

文档也划定了验证边界：离线已用 44.1/48/96 kHz 的音调、静音、幅度切换和超限脉冲检查了增益、用户音量比例及峰值边界；浏览器验证使用真实 B 站视频与开发扩展；长期播放、更多内容类型和 Firefox 仍需进一步听感与兼容验证，资源释放计数也不能代替长期堆内存分析。这是对自身局限性的诚实说明。

参与贡献：分支、Commit 与 i18n 约定

按贡献指南的约定：

常驻分支：Main分支用于错误修复、新功能开发、性能改进或 i18n 文件的修改；
临时分支：feat/提交新功能，doc/只改文档不改功能，fix/修复错误。

Commit 消息遵循 Angular 规范，常用类型包括feat（新功能）、fix（修复 Bug）、docs（文档更新）、style（不影响代码含义的格式改动）、refactor（重构）、test（测试）、chore（构建/工具链）、perf（性能）、ci（持续集成），也欢迎增加 scope 与 footer，例如fix(dock): xxx并附带变更描述与相关 PR 链接。

i18n 方面有一条硬性约定：请手动维护 i18n 国际化文件，不要使用i18n Ally等扩展，因为自动工具会不确定翻译放置位置或误删代码注释。仓库内语言文件位于 src/_locales（简体中文、繁体中文、英文、粤语）。

鸣谢与依赖生态

README 的鸣谢部分列明了该项目得以成立的技术基础：基础项目 [BewlyBewly]、项目模板 [vitesse-webext]（Vite + WebExtension 脚手架）、访问密钥参考 [UserScripts/bilibiliHome] 与 [bilibili-app-recommend]、部分功能实现参考 [Bilibili-Evolved]，以及 API 文档参考 [bilibili-API-collect]。依赖栈也能在 package.json 中印证：Vue 3 + Pinia + vue-i18n + UnoCSS + wxt + tsup 构成了整个前端与打包体系，simple-git-hooks在 pre-commit/pre-push 阶段强制执行 lint 与类型检查。

小结

BewlyCat 的完整价值在于“小而精”的取舍：在 BewlyBewly 基础上新增了后台打开、播放器样式联动、快捷键自定义、倍速记忆、随机播放、局部音量均衡等实用能力，同时砍掉字体与旧版顶栏把体积压缩到 600K。对普通用户而言，从三家应用商店在线安装即可；对开发者而言，一条pnpm install && pnpm dev && pnpm start:chromium就能拉起带热重载的调试环境。若要深入理解其最有技术含量的模块，建议从 docs/local-loudness.md 与 src/inject/audio/localLoudness.ts 的组合阅读开始——那是一个将 AudioWorklet、BS.1770 响度算法与 WebExtension 生命周期管理完整落地的参考实现。