BewlyBewly 贡献指南：开发环境搭建、构建打包与分支 Commit 规范详解

前端【免费下载链接】BewlyBewlyJust make a few small changes to your Bilibili homepage. (English | 简体中文 | 正體中文 | 廣東話)项目地址https://gitcode.com/gh_mirrors/be/BewlyBewly点击查看免费下载本指南以 docs/CONTRIBUTING-cmn_CN.md 为骨架完整梳理 BewlyBewly 浏览器扩展的本地开发流程Chrome/Edge 与 Firefox 双浏览器、开发与构建双模式并结合仓库内 package.json、vite.config.ts、src/manifest.ts 等源码级证据深入讲解从pnpm dev到打包上线的完整工程管线以及项目贡献者必须遵守的分支、Commit 与 i18n 国际化维护规范。读完本文你将能够独立搭建 BewlyBewly 的开发环境、完成 Chrome 与 Firefox 两种目标浏览器的开发调试与构建打包并遵循项目约定提交符合规范的高质量 PR。项目概览与工程定位BewlyBewly 是一个基于 Manifest V3 的浏览器扩展目标是在不侵入 B 站业务逻辑的前提下通过注入脚本与样式的方式小幅改造Bilibili 首页体验。其工程核心是一套基于 Vite 的多入口构建方案options设置页与popup弹窗页作为 Vite 的 HTML 入口background后台脚本与contentScripts内容脚本则由 tsup 与独立 Vite 配置分别打包最终统一输出为一个标准 WebExtension 目录。从 package.json 可以看到项目的核心元信息包名bewly-bewly、版本0.40.2、包管理器固定为pnpm9.5.0项目描述为 Just make a few small changes to your Bilibili homepage.。整个仓库采用 pnpm 作为唯一包管理器因此以下所有命令均以pnpm前缀执行。开发环境准备必需工具按贡献指南要求本地开发前需确保安装以下工具工具用途说明Node.js运行构建工具链建议使用 LTS 版本pnpm包管理与脚本执行仓库packageManager字段固定为pnpm9.5.0建议保持同版本以免出现依赖行为差异Visual Studio Code开发 IDE项目 ESLint、Vue SFC、TypeScript 配置均围绕 VS Code 生态设计安装依赖进入仓库根目录后执行pnpm install值得注意的是pnpm install之后会通过postinstall钩子自动执行npx simple-git-hooks见 package.json安装 git 钩子。该钩子的配置为pre-commit: pnpm lint-staged而lint-staged对所有暂存文件执行eslint --fix见 package.json。也就是说每次提交前暂存区的所有文件都会自动被 ESLint 自动修复这是项目保证代码风格一致的第一道防线无需手动干预。构建管线总览读懂 package.json 的脚本矩阵要理解贡献指南中每条命令的含义先看 package.json 中定义的核心脚本矩阵脚本命令内容作用devclear NODE_ENVdevelopment run-p dev:*Chrome/Edge 开发模式先清理旧产物再并行运行dev:prepare、dev:web、dev:js、dev:bgdev-firefoxclear-firefox NODE_ENVdevelopment FIREFOXtrue run-p dev:*Firefox 开发模式通过FIREFOXtrue环境变量切换目标buildNODE_ENVproduction run-s clear build:web build:prepare build:js build:bgChrome/Edge 生产构建串行执行build-firefoxNODE_ENVproduction FIREFOXtrue run-s ...Firefox 生产构建build-safariNODE_ENVproduction SAFARItrue run-s ...Safari 构建供convert-safari转换用start:chromiumweb-ext run --source-dir ./extension --targetchromium自动启动 Chrome 并加载扩展start:firefoxweb-ext run --source-dir ./extension-firefox --targetfirefox-desktop自动启动 Firefox 并加载扩展lint/lint:fixeslint/eslint --fix全量代码检查与自动修复testvitest test运行单元测试typecheckvue-tscTypeScript 类型检查其中dev:*的四个子任务分别对应dev:prepare→esno scripts/prepare.ts生成开发用的 stubindex.html、拷贝assets资源并生成manifest.json详见下文dev:web→vite启动 Vite 开发服务器默认端口3303定义于 scripts/utils.tsdev:js→vite build --config vite.config.content.ts --mode development以开发模式构建 contentScriptsdev:bg→tsup --watch ./src以 watch 模式打包 background 脚本。正是这种Vite 服务器 tsup watch web-ext 自动加载的组合构成了贡献指南中所说的每次修改后自动重新加载、刷新网页即可看到变更的开发体验。prepare 脚本做了什么scripts/prepare.ts 在开发与构建阶段都会被执行dev:prepare/build:prepare它负责三件事创建目标输出目录extension/extension-firefox/extension-safari之一由环境变量决定把 assets 目录拷贝到输出目录供manifest.json中的图标与rules.json引用通过npx esno ./scripts/manifest.ts调用 scripts/manifest.ts动态生成manifest.json。其中 manifest 生成逻辑src/manifest.ts充分体现了一套源码、多浏览器适配的设计Chrome 使用service_worker作为 background而 Firefox/Safari 则改用background.scripts因为 Manifest V3 中 Firefox 不支持persistent: true的 service worker 语义同时 Firefox 版额外申请webRequest、webRequestBlocking、cookies权限并写入browser_specific_settings.gecko.id addonbewlybewly.com。content_scripts 覆盖了www.bilibili.com、search.bilibili.com、space.bilibili.com等十余个 B 站域名的document_start时机并额外通过world: MAIN注入一个页面主世界脚本src/inject/index.js。Chrome / Edge 开发贡献指南为 Chrome/Edge 提供了两种开发方式二者本质区别在于谁负责加载扩展。方式一web-ext 全自动启动推荐在仓库根目录依次执行# 安装依赖 pnpm install # 创建一个用于存储登录状态的扩展程序文件夹 mkdir web-ext-profile # 运行项目 pnpm dev # 自动打开一个新的 Chrome 窗口并打开 Bilibili 网站 pnpm start:chromium其中pnpm start:chromium实质是执行web-ext run --source-dir ./extension --targetchromium。web-ext 的默认行为可以在 package.json 的webExt配置段中看到keepProfileChanges: true保留浏览器 Profile 变更firefoxProfile/chromiumProfile均指向刚创建的./web-ext-profilestartUrl默认打开https://www.bilibili.com/。web-ext-profile目录的意义在于它保存了浏览器的登录态Cookie、本地存储等这样扩展在调试时可以直接使用已登录的 B 站账号避免每次启动都重新扫码登录。开发模式下每次修改源码构建管线会自动重新编译Vite 负责页面模块的 HMR而 vite-mv3-hmr.ts 这个自定义插件负责把 HMR 更新写回磁盘writeToDisktsup watch 则实时重打 background 脚本。因此你只需要刷新网页即可看到最新变更无需手动重载扩展。方式二浏览器手动加载pnpm install pnpm dev然后在浏览器地址栏输入chrome://extensions/Chrome或edge://extensions/Edge回车打开开发者模式点击加载已解压的扩展程序选择生成的extension/文件夹即可。注意手动模式下Vite 的 HMR 不会自动生效于扩展页面因此每次修改后需要点击扩展的重新加载按钮并刷新页面才能看到变更贡献指南中建议配合 Extensions Reloader 一类工具简化操作。这一限制的根本原因是扩展代码运行在浏览器扩展沙箱中与 Vite 开发服务器之间的 HMR 通道scripts/client.ts 中的mv3client.mjs客户端仅在 web-ext 启动时通过调试端口建立完整链路。Chrome / Edge 构建要产出可分发、可提交商店的正式包运行pnpm build构建完成后产物打包到extension/目录。该目录内包含manifest.json、dist/background 与 contentScripts 等、assets/图标与 assets/rules.json 网络规则等完整扩展结构。Vite 的构建输出路径定义在 vite.config.tsextension/dist非 Firefox/Safari 时。如需进一步产出extension.zip/extension.crx可执行pnpm pack内部调用pack:zip、pack:crx见 package.json。Firefox 开发Firefox 与 Chrome 在 Manifest V3 的 API 语义上存在差异项目通过FIREFOXtrue环境变量在整个构建链路中切换输出目录extension-firefox与 manifest 形态background 脚本、权限列表详见 scripts/utils.ts 与 src/manifest.ts。方式一web-ext 全自动启动# 安装依赖 pnpm install # 创建一个用于存储登录状态的扩展程序文件夹 mkdir web-ext-profile # 运行项目 pnpm dev-firefox # 自动打开一个新的 Firefox 窗口并打开 Bilibili 网站 pnpm start:firefoxpnpm start:firefox对应web-ext run --source-dir ./extension-firefox --targetfirefox-desktop同样复用./web-ext-profile保存登录态。方式二浏览器手动加载pnpm install pnpm dev-firefox然后在 Firefox 地址栏输入about:addons进入Extensions页面点击Debug Add-ons临时载入附加组件选择生成的extension-firefox/文件夹。Firefox 构建pnpm build-firefox产物打包到extension-firefox/目录。该目录结构与extension/平行但 manifest 与权限按 Firefox 语义生成。若要产出商店提交所需的extension-firefox.zip与源码包可运行pnpm pack:zip-firefox与pack:zip-firefox-sources后者通过git archive从 HEAD 导出源码。工程质量配套lint、测试与类型检查在提交代码之前建议在本地完整跑一遍工程自检# 代码风格检查提交时 lint-staged 已自动做 --fix这里做全量确认 pnpm lint # 单元测试基于 vitest配置在 vite.config.ts 的 test 字段jsdom 环境 全局注入 pnpm test # TypeScript 类型检查vue-tsc覆盖 Vue SFC 与普通 TS 文件 pnpm typecheck仓库内已有的测试样例包括 src/tests/uriParse.spec.ts解析bilibili://video/...深链、判定竖屏视频与 src/tests/demo.spec.ts新增逻辑时可参照这两个文件补充测试用例。贡献流程与分支规范常驻分支贡献指南明确规定Main 分支承担所有日常开发任务错误修复、新功能开发、性能改进以及对国际化i18n文件的修改都直接基于main分支进行。临时分支分支前缀用途feat/提交新的功能特性doc/专门用于修复文档不涉及功能改动fix/专门用于修复开发过程中出现的错误按此约定一个新增关注页筛选功能的 PR 分支应命名为feat/following-filter纯文档修正则使用doc/xxx前缀以确保从分支名即可判断 PR 的性质。Commit 规范贡献指南要求参照 Angular commit message guidelines 编写提交信息支持以下类型类型含义feat新功能fix修复 Bugdocs文档更新style不影响代码含义的更改空格、格式、缺少分号等refactor重构代码test添加或更新测试chore构建过程或工具链的变更perf性能改进ci持续集成/交付的变更除类型外还鼓励附加scope与footer。指南给出了典型示例fix(dock): xxx 变更描述 相关 PR: url其中fix(dock)中的dock即为 scope对应仓库内的 Dock 模块——scope 通常取自被改动模块名如topbar、videoCard、settings等可对照 src/components 目录结构footer 中可补充关联的 PR 地址等上下文信息便于维护者追溯变更来源。I18n 国际化维护规范BewlyBewly 面向多语言用户国际化文件位于 src/_locales 目录当前包含四个语言版本cmn-CN.yml简体中文cmn-TW.yml正体中文en.yml英文jyut.yml粤语这些 YAML 文件通过intlify/unplugin-vue-i18n在构建期打包进应用配置见 vite.config.ts 的include: [./src/_locales/**]运行时由 src/utils/i18n.ts 中的 vue-i18n 实例读取默认语言为英文并以此作为 fallback。贡献指南对翻译工作提出两条硬性要求遇到不熟悉的语言时可以使用你已经翻译过的另一种语言通常指英文作为占位翻译并在 PR 中明确指出你无法翻译的语言交由擅长该语言的维护者补齐必须手动维护 i18n 文件严禁使用i18n Ally等扩展自动维护。指南明确说明原因使用 i18n Ally 会导致翻译条目被放置到不确定的位置、或误删代码注释破坏 YAML 文件的既有组织方式。手动维护时的正确做法是对照 en.yml 的键层级结构在其余三个语言文件中保持完全一致的键路径与缩进仅替换文案值新增 key 时四个文件必须同步更新。提交 PR 前的检查清单综合以上规范整理一份贡献者自查清单分支命名符合feat/、doc/、fix/前缀约定pnpm lint、pnpm test、pnpm typecheck全部通过pre-commit 钩子会自动执行 lint-staged 的eslint --fixCommit message 使用规范类型必要时附上 scope 与 footer涉及界面文案时src/_locales 下四个语言文件同步更新且翻译不熟的语言已显式标注文档类改动如本文所属的 docs 目录使用doc/分支与功能改动分离。延伸阅读English 版贡献指南、正體中文版、廣東話版 —— 同一指南的多语言版本术语可与中文版对照scripts/prepare.ts 与 scripts/manifest.ts —— 构建期 manifest 与 stub 生成逻辑vite.config.ts 与 vite-mv3-hmr.ts —— 构建配置与 MV3 HMR 实现细节src/tests/uriParse.spec.ts —— 测试编写范式参考。赞分享前端【免费下载链接】BewlyBewlyJust make a few small changes to your Bilibili homepage. (English | 简体中文 | 正體中文 | 廣東話)项目地址https://gitcode.com/gh_mirrors/be/BewlyBewly点击查看免费下载相关推荐BewlyBewly 开发与贡献指南从环境搭建、多浏览器构建到提交规范BewlyBewly 开发与贡献指南从环境搭建、多浏览器构建到提交规范 BewlyBewly 是一款通过内容脚本与样式适配对 Bilibili 主页进行深度改前端kotaemon 开发者贡献指南环境搭建、包结构解析与 PR 协作规范kotaemon 开发者贡献指南环境搭建、包结构解析与 PR 协作规范 本篇指南以 docs/development/contributing.md http人工智能大模型RAG向量数据库后端Bruno 本地开发与贡献实战指南环境搭建、构建测试与分支规范全解析Bruno 本地开发与贡献实战指南环境搭建、构建测试与分支规范全解析 本文以仓库中的土耳其语版贡献指南 docs/contributing/contribut开发工具接口测试桌面应用CLI上一篇Mongoku开发指南基于SvelteKit构建高性能Web界面下一篇终极指南如何使用Atlantis简化Terraform基础设施环境切换 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考