企业官网建设流程全解析

• 前端

本指南以 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、包管理器固定为pnpm@9.5.0，项目描述为 "Just make a few small changes to your Bilibili homepage."。整个仓库采用 pnpm 作为唯一包管理器，因此以下所有命令均以pnpm前缀执行。

开发环境准备

必需工具

按贡献指南要求，本地开发前需确保安装以下工具：

安装依赖

进入仓库根目录后执行：

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 中定义的核心脚本矩阵：

其中dev:*的四个子任务分别对应：

• dev:prepare→esno scripts/prepare.ts：生成开发用的 stubindex.html、拷贝assets资源并生成manifest.json（详见下文）；
• dev:web→vite：启动 Vite 开发服务器（默认端口3303，定义于 scripts/utils.ts）；
• dev:js→vite build --config vite.config.content.ts --mode development：以开发模式构建 contentScripts；
• dev:bg→tsup --watch ./src：以 watch 模式打包 background 脚本。

正是这种"Vite 服务器 + tsup watch + web-ext 自动加载"的组合，构成了贡献指南中所说的"每次修改后自动重新加载、刷新网页即可看到变更"的开发体验。

prepare 脚本做了什么

scripts/prepare.ts 在开发与构建阶段都会被执行（dev:prepare/build:prepare），它负责三件事：

1. 创建目标输出目录（extension/extension-firefox/extension-safari之一，由环境变量决定）；
2. 把 assets 目录拷贝到输出目录，供manifest.json中的图标与rules.json引用；
3. 通过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 = addon@bewlybewly.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 --target=chromium。web-ext 的默认行为可以在 package.json 的webExt配置段中看到：keepProfileChanges: true保留浏览器 Profile 变更，firefoxProfile/chromiumProfile均指向刚创建的./web-ext-profile，startUrl默认打开https://www.bilibili.com/。

web-ext-profile目录的意义在于：它保存了浏览器的登录态（Cookie、本地存储等），这样扩展在调试时可以直接使用已登录的 B 站账号，避免每次启动都重新扫码登录。

开发模式下每次修改源码，构建管线会自动重新编译：Vite 负责页面模块的 HMR，而 vite-mv3-hmr.ts 这个自定义插件负责把 HMR 更新"写回磁盘"（writeToDisk），tsup 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.ts：extension/dist（非 Firefox/Safari 时）。如需进一步产出extension.zip/extension.crx，可执行pnpm pack（内部调用pack:zip、pack:crx，见 package.json）。

Firefox 开发

Firefox 与 Chrome 在 Manifest V3 的 API 语义上存在差异，项目通过FIREFOX=true环境变量在整个构建链路中切换输出目录（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:firefox

pnpm start:firefox对应web-ext run --source-dir ./extension-firefox --target=firefox-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分支进行。

临时分支

按此约定，一个新增"关注页筛选"功能的 PR 分支应命名为feat/following-filter，纯文档修正则使用doc/xxx前缀，以确保从分支名即可判断 PR 的性质。

Commit 规范

贡献指南要求参照 Angular commit message guidelines 编写提交信息，支持以下类型：

除类型外，还鼓励附加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。

贡献指南对翻译工作提出两条硬性要求：

1. 遇到不熟悉的语言时，可以使用你已经翻译过的另一种语言（通常指英文）作为占位翻译，并在 PR 中明确指出你无法翻译的语言，交由擅长该语言的维护者补齐；
2. 必须手动维护 i18n 文件，严禁使用i18n Ally等扩展自动维护。指南明确说明原因：使用 i18n Ally 会导致翻译条目被放置到不确定的位置、或误删代码注释，破坏 YAML 文件的既有组织方式。

手动维护时的正确做法是：对照 en.yml 的键层级结构，在其余三个语言文件中保持完全一致的键路径与缩进，仅替换文案值；新增 key 时四个文件必须同步更新。

提交 PR 前的检查清单

综合以上规范，整理一份贡献者自查清单：

1. 分支命名符合feat/、doc/、fix/前缀约定；
2. pnpm lint、pnpm test、pnpm typecheck全部通过（pre-commit 钩子会自动执行 lint-staged 的eslint --fix）；
3. Commit message 使用规范类型，必要时附上 scope 与 footer；
4. 涉及界面文案时，src/_locales 下四个语言文件同步更新，且翻译不熟的语言已显式标注；
5. 文档类改动（如本文所属的 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 —— 测试编写范式参考。

• 前端