代码贡献指南

June 12, 2026 · View on GitHub

欢迎

很高兴能有更多人参与到本项目的开发中，无论是添加新功能，修复 Bug 还是改进文案都是可以的。由于B站的改动很频繁，脚本需要被不断地修改以适应B站的变化。如果你想为本项目贡献一份力量，请认真阅读以下指南。

技术栈

BLTH 是一个基于 Vue3, Element Plus, vite-plugin-monkey 和 Typescript 的用户脚本。如果想要贡献代码，你至少需要有 Vue3 和 Typescript 基础。

环境搭建

安装 Node.js (建议安装最新的 LTS 版本)
如果使用 Visual Studio Code，安装以下几个拓展（打开项目时会提示你安装）：Vue - Official, ESLint, Styleint, EditorConfig for VS Code, Prettier - Code formatter

开始

首先 Fork 本项目并 Clone 至本地。

git clone https://github.com/your-username/BLTH.git

然后把原仓库添加为 upstream，再基于上游的 dev 分支创建本地分支。

git remote add upstream https://github.com/andywang425/BLTH.git
git fetch upstream
git switch -c your-dev-branch upstream/dev

后续如果需要同步上游的 dev 分支：

git fetch upstream
git switch your-dev-branch
git merge upstream/dev

安装依赖：

npm install

接着使用以下命令在浏览器中安装脚本并启动 Vite，然后你就可以开始写代码啦。

npm run dev

得益于 Vite 的模块热更新（HMR）功能，如果仅修改了 UI 相关代码，可以直接在浏览器中看到结果。其余情况下可能需要你手动刷新页面。

项目概览

分支

master: master 分支是发布分支，准备发版时会通过 Pull Request 将 dev 合并到 master，合并后会触发 GitHub Actions 构建并创建 Release
dev: dev 分支是开发分支。日常开发请基于 upstream/dev 创建独立的功能分支（不要直接在 fork 的 master 上改动），发起 PR 时记得把目标分支设置为 dev

目录结构

BLTH
├─.vscode
├─dist                     npm run build 得到的用户脚本
├─scripts                  一些npm scripts，通过 npm run ... 调用
└─src
    ├─assets               资源文件
    │  └─css
    ├─components           vue组件
    │  └─icons             图标组件
    ├─library              库文件
    │  ├─...               每个文件夹代表一个库，此处省略
    ├─modules              模块
    │  ├─...               这里有很多模块，此处省略
    │  └─default           默认模块，性质较特殊
    ├─stores               Pinia store
    └─types                typescript 类型定义

示例

如果你还是不太清楚怎么做，下面是新增一个功能模块的简单流程。

假设现在B站给主站每日任务新添加了一个任务：给视频点赞。

首先打开 src/modules 文件夹，你会发现已经有了 dailyTasks/mainSiteTasks/ 这个文件夹，那么你只需在这个文件夹下新建一个 ts 文件即可。内容大概如下：

import BaseModule from '@/modules/BaseModule'
// import ...

class LikeTask extends BaseModule {
  // ...
}

export default LikeTask

具体写法可以参考已经写好的模块。

你写的这个模块肯定会有相关的配置项（至少得有一个开启/关闭的选项吧），打开 src/types/storage.d.ts，加上该模块配置信息的类型声明。

接着打开 src/library/storage/defaultValue.ts，加上该模块配置信息的默认值。

点赞涉及到对B站API的请求。在 src/library/bili-api/ 中找找看有没有给视频点赞的API，如果没有得自己添加。参考已有的API即可。

点赞的视频从哪来？如果仔细阅读代码你会发现 src/stores/useBiliStore.ts 的 dynamicVideos 里已经存储了许多动态视频，你可以直接用。如果有特殊需求，自己获取视频当然也是可以的。

完成模块的编写后，在 src/modules/dailyTasks/mainSiteTasks/index.ts 中添加新模块的导出。

因为脚本已经有了主站任务界面 src/components/MainSiteTasks.vue，所以你只需要在该组件中加上新功能的 UI 即可。

为了更好的用户体验，建议加上帮助信息（Info 组件）、模块状态和模块再运行功能（TaskStatus 组件）。参考已有的模块即可。

代码风格

编写的代码需要能够通过 ESlint 和 Stylelint 检查。在你编写代码的过程中 ESLint 和 Stylelint 拓展会实时地检查打开的代码文件。

你也可以使用以下命令检查所有文件：

npm run lint

在你完成代码编写后，请运行以下命令格式化所有代码：

npm run format

编码准则

强制性

对于 src/library/bili-api/ 中的每个 API，必须为其请求参数和响应内容编写详细的类型定义。transform 和 quicktype 或许会有帮助
如果添加了新的第三方库或资源文件，请修改 vite.config.ts 使其通过 @require 或 @resource 引入

建议性

尽可能详细地写类型定义，必要时才使用any/unknown
为逻辑复杂的代码编写注释

编译

开发完成后记得编译并测试一下最终的成品。使用以下命令编译脚本：

npm run build

这会在dist文件夹下生成一个后缀为.user.js的文件和一个后缀为.min.user.js的文件，分别是未压缩的和压缩后的用户脚本。

最后输入以下命令在浏览器中打开预览页面：

npm run preview

然后浏览器会打开一个页面，页面上有两个脚本的安装链接（未压缩的和压缩后的），选择一个安装即可。

已知问题

如果要开发或调试运行时机很早的模块，建议先编译脚本（build 或 build-only）然后运行编译后的脚本。在 dev 状态下调试这类功能可能会因为脚本被注入得太晚从而无法很好地进行测试。

commit 规范

请在 commit message 中简单阐述一下改动内容，建议使用类似约定式提交的格式。

发起 PR

把你的分支合并到主仓库的dev分支即可。