Bilibili-Evolved深度实战指南：从零定制你的专属哔哩哔哩增强脚本

Bilibili-Evolved深度实战指南：从零定制你的专属哔哩哔哩增强脚本

【免费下载链接】Bilibili-Evolved强大的哔哩哔哩增强脚本项目地址: https://gitcode.com/gh_mirrors/bi/Bilibili-Evolved

Bilibili-Evolved是一款以"模块化"为核心的哔哩哔哩增强脚本，它不预装任何功能，而是把下载、弹幕处理、界面改造等能力拆成一个个可独立安装的组件，让技术型用户按需拼装出属于自己的B站体验。为什么值得深入研究？因为它不只是"开箱即用"的工具，更是一套完整的用户脚本工程范本——TypeScript 编写、webpack 打包、Vue 驱动界面、shadow-root 隔离样式，源码里藏着大量可以迁移复用的工程实践。这篇文章将从"第一小时上手"一路拆解到"源码级原理"，最后带你亲手写一个组件，完成一次从使用者到开发者的完整旅程。

能力速览：五个关键词看懂它凭什么"强大"

在动手之前，先用五个关键词建立对项目的整体认知：

这套分层架构的核心思想是"核心稳定、功能游离"：src/core/只做基础设施，所有具体功能都被隔离到registry/中按目录分类，新增一个功能基本不影响其他模块。

设置面板集中管理组件开关与选项，是日常使用频率最高的入口

场景化上手：技术用户的第一小时

假设你刚装好 Tampermonkey 或 Violentmonkey，接下来这一小时会经历什么？

第 0-5 分钟：安装与初次见面。从正式版/预览版链接安装脚本后打开任意B站页面，左侧边缘会浮出两个入口——功能面板和设置面板。注意一个容易误判的点：全新安装的脚本实际上没有任何功能，它更像一个"空壳运行时"，这恰恰是它与其他全家桶式脚本最大的设计差异。

第 5-30 分钟：按需装配。打开设置面板，左下角有组件/插件/样式三种管理入口，支持三种添加方式：批量（粘贴多个直链一次性安装）、浏览（载入本地功能文件）、在线（打开在线仓库窗口）。首次配置建议按这个顺序尝试：

1. 先装夜间模式（registry/lib/components/style/dark-mode/），感受主题色全局应用的效果；
2. 再装自定义顶栏（registry/lib/components/style/custom-navbar/），把导航重构为你习惯的布局；
3. 最后装一个视频类组件（如弹幕过滤），体验功能级定制。

第 30-60 分钟：理解配置即代码。每个组件的选项都由 TypeScript 元数据声明驱动，例如自定义顶栏的globalFixed（全局固定）、fill（主题色填充）、blur（背景模糊）、transparent（透明填充）等，这些选项会统一渲染成设置面板里的控件，无需每个组件各自写 UI。

组件管理面板是"按需装配"模式的核心操作台，支持批量与在线两种安装路径

原理深潜：从"数据流向"看脚本如何在B站页面上运转

理解这个项目，关键是抓住一条数据流：生命周期 → 设置代理 → 组件注册 → 隔离渲染。下面按这条链路逐个拆解。

第一环：生命周期——代码在什么时机执行

src/core/life-cycle.ts定义了四个关键节点，它们决定了增强逻辑的启动顺序：

export enum LifeCycleEventTypes { Start = 'be:start', StyleLoaded = 'be:style-loaded', ComponentsLoaded = 'be:components-loaded', End = 'be:end', }

配合headLoaded、contentLoaded、fullyLoaded三个 Promise 封装，组件可以精确选择"head 就绪后注入样式"还是"DOM 完全加载后再挂逻辑"。对B站这种动态渲染的 SPA 页面，src/core/observer.ts提供的 DOM 观察器会在节点变化时回调，保证增强功能对异步加载的内容同样生效。

第二环：设置代理——一次读写，处处响应

src/core/settings/目录里是整套设置系统：proxy.ts用 Proxy 包装设置对象，任何组件通过getComponentSettings读取或修改选项时，listener.ts会向所有订阅者广播变更。这意味着你在设置面板拨动一个开关，正在运行的相关组件会实时响应，无需刷新页面。types.ts中Settings接口统一管理components、plugins、userStyles、userComponents等区块，为设置导入/导出提供了结构基础。

第三环：组件注册——元数据驱动一切

src/components/component.ts维护全局componentsMap，组件通过defineComponentMetadata/defineOptionsMetadata（定义在src/components/define.ts）声明名称、入口、样式、选项等元数据。注册后由install-feature.ts按需拉取代码，实现"用到才加载"。这也是脚本性能可控的关键：未启用的组件不会进入运行时。

第四环：隔离渲染——不改坏B站原有页面

增强脚本最怕两件事：污染全局样式、被B站前端框架干扰。项目的解法是src/core/shadow-root/这一整套 shadow DOM 工具：ShadowDomEntry负责把组件挂载进隔离的 DOM 子树，ShadowRootStyles管理样式注入，配合dom-observer.ts处理动态节点。这样自定义顶栏、首页改版等重样式组件无论怎么折腾，都不会泄漏影响B站原生页面。

进阶实战：亲手写一个可安装的本地组件

理解了"元数据驱动"，写组件就变成填空式工作。以"隐藏动态页侧边卡片"类的小功能为例，标准骨架如下：

import { defineComponentMetadata, defineOptionsMetadata } from '@/components/define' const options = defineOptionsMetadata({ keyword: { defaultValue: '推广', displayName: '过滤关键词', }, }) export default defineComponentMetadata({ name: 'my-feed-filter', displayName: '我的动态过滤器', entry: async () => { const { myFilter } = await import('./my-filter') myFilter() }, options, urlInclude: ['https://t.bilibili.com/*'], })

要点有三：entry用动态 import 实现懒加载；options的元数据会自动生成设置面板控件；urlInclude限定生效页面。开发完成后，在组件管理面板选择"浏览"载入本地.user.js格式的文件即可安装调试。

真正的项目里，registry/lib/components/feeds/filter/就是一个比这复杂得多的范本——它包含options.ts（选项定义）、pattern.ts（匹配规则）、state.ts（过滤状态）、plugin.ts（页面插件）、以及多个 Vue 面板组件，适合作为深入学习组件内部分层的参考。另外dev-tools/feature-docs/会扫描各组件目录下的index.md自动生成doc/features/features.md文档，所以为组件写文档是强制规范而非可选项。

调优与避坑：可复用的性能技巧与问题清单

项目对性能要求极高（README 明确给出了最低 8GB 内存、1920x1080 的配置门槛），因此沉淀了不少可复用的优化经验：

性能优化三件套

• 懒加载成瘾：所有功能代码都走动态import，src/core/lazy-panel.ts进一步把设置面板等重量级 UI 推迟到真正打开时才渲染；
• 观察器精准化：observer.ts只监听必要的节点类型与子树，避免全页面高频 MutationObserver 造成掉帧；
• 生命周期对齐：样式类功能挂在headLoaded，逻辑类挂contentLoaded，宁可稍晚启动也不阻塞首屏。

常见问题清单

• 组件装了没效果：先查urlInclude是否覆盖当前页面，再确认是否被其他组件冲突（如"直播信息扩充"与动态侧边卡片过滤的已知冲突）；
• 页面卡顿：优先检查是否同时启用了多个重样式组件，夜间模式与首页改版都属于高开销模块；
• 调试入口：src/core/utils/log.ts提供分级日志，配合src/core/performance/下的component-trace.ts、plugin-trace.ts可以精确追踪每个组件/插件的耗时。

生态与参与：从使用者到贡献者的三条路径

如果你想更进一步，项目提供了清晰的参与通道：

• 贡献组件：在registry/lib/components/对应分类下新建目录，实现逻辑、补充index.md文档，提交后由dev-tools/pr-check/自动检查元数据与文档是否合规；
• 本地二次开发：克隆仓库（git clone https://gitcode.com/gh_mirrors/bi/Bilibili-Evolved），dev-tools/dev-server/提供带热更新的本地开发服务器，registry/webpack/区分了核心、组件、插件三类构建入口；
• 翻译与文档：src/components/i18n/承载多语言支持，文案与文档同样是重要的贡献方向。

收尾：把"增强脚本"当成工程来读

回到开头的问题——为什么技术用户值得深入研究 Bilibili-Evolved？因为它用一套完整的工程化实践回答了一个常见难题：如何在别人家的复杂网页上，安全、高效、可维护地注入自己的改造。分层架构、元数据驱动、shadow DOM 隔离、按需加载，这些概念每一个单独拿出来都能写成一篇文章，而这里它们被组合成了一个可运行、可扩展的真实项目。

下一步行动建议很直接：先装好脚本，用一周时间按需装配你的组件组合；再挑一个你最常用的组件读它的源码；最后照着本文的骨架写一个自己的组件。当你能在设置面板里看到自己定义的那个开关时，你就真正读懂了"增强脚本"这三个字。

关于面板是版本管理与配置备份的枢纽，设置导入/导出功能值得养成定期使用的习惯

【免费下载链接】Bilibili-Evolved强大的哔哩哔哩增强脚本项目地址: https://gitcode.com/gh_mirrors/bi/Bilibili-Evolved