Bitwarden 浏览器扩展Browser Extension开发与构建指南基于 Web Extension API 与 Angular 的多浏览器实现【免费下载链接】clientsBitwarden client apps (web, browser extension, desktop, and cli).项目地址: https://gitcode.com/GitHub_Trending/cl/clients导读本文以 apps/browser/README.md 为骨架系统讲解 Bitwarden 客户端仓库中浏览器扩展的定位、技术选型与多浏览器构建机制。该扩展使用Web Extension API 与 Angular编写可同时产出 Chrome、Edge、Firefox、Opera、Safari 五个平台的产物并支持 Manifest V2/V3 双版本切换。读完本文你将掌握该扩展的目录结构、构建命令、Manifest 生成原理以及跨浏览器兼容的关键抽象层BrowserApi能够独立在本地完成各浏览器的开发与打包流程。一、项目定位客户端家族中的浏览器扩展Bitwarden 客户端仓库GitHub_Trending/cl/clients采用 monorepo 结构包含web、browser、desktop、cli四大应用。其中 apps/browser 即浏览器扩展应用在 project.json 中以projectType: application声明sourceRoot指向apps/browser/src打上了scope:browser与type:app标签。原文档开门见山地给出了该扩展的两项核心技术事实使用Web Extension API而非各家浏览器的私有 API编写使用Angular作为 UI 框架。这一技术选型是跨浏览器交付Chrome / Edge / Firefox / Opera / Safari的基础Web Extension API 是一套被主流浏览器共同支持的标准化扩展接口配合仓库内的抽象层与构建时 Manifest 变换实现一套代码、多端产出。此外README 还展示了项目的持续集成与本地化状态仓库通过 GitHub Actions 在 main 分支上执行build-browser.yml工作流持续构建浏览器扩展并通过 Crowdin 管理多语言翻译_locales目录下共 63 个语言 JSON 文件。二、仓库内文档导航从哪里开始原 README 明确指向 Bitwarden 官方 Contributing Documentation 的 Browser 章节建议读者按官方指引获取构建说明、推荐工具链与代码风格建议。需要说明的是该链接指向仓库外站点而在当前仓库内部同样存在可直接查阅的权威资料优先级更高apps/browser/CLAUDE.md浏览器扩展的铁律清单浓缩了跨浏览器开发中最容易踩坑的规则详见下文第六节apps/browser/package.json所有构建、打包、测试脚本的权威入口apps/browser/project.jsonNx 目标定义覆盖 build / serve / test / lint 全部任务及其各浏览器配置。三、构建体系五浏览器 × 双 Manifest 版本3.1 Nx 构建目标与输出产物在 project.json 中build目标使用nx/webpack:webpack执行器主入口为apps/browser/src/popup/main.ts默认配置为chrome-dev。整个构建矩阵由三个环境变量驱动环境变量取值含义BROWSERchrome/edge/firefox/opera/safari目标浏览器决定 Manifest 变换与产物目录MANIFEST_VERSION2/3使用的 Web Extension Manifest 版本NODE_ENVdevelopment/production是否为生产构建是否应用 Beta/生产配置build 目标下的 configurations 覆盖了所有组合例如chrome/chrome-devMV3生产/开发firefox/firefox-mv2及其 dev 变体safari/safari-mv2及其 dev 变体edge、opera及其 dev 变体产物统一输出到dist/apps/browser/下对应的浏览器目录例如dist/apps/browser/chrome-dev、dist/apps/browser/firefox-mv2。值得注意的还有以commercial-前缀命名的配置如commercial-chrome、commercial-firefox-mv2等。它们并不使用开源版的apps/browser/webpack.config.js与src/popup/main.ts而是切换为bitwarden_license/bit-browser/webpack.config.js与bitwarden_license/bit-browser/src/popup/main.ts对应bitwarden_license/bit-browser目录下的商业版扩展入口。3.2 npm 脚本最常用的构建入口对于开发者来说apps/browser/package.json 中的脚本是日常主力。当前扩展版本为2026.9.0核心脚本包括# 开发构建默认 ChromeMV3 npm run build:chrome # 各浏览器开发构建 npm run build:edge npm run build:firefox npm run build:opera npm run build:safari # 生产构建NODE_ENVproduction npm run build:prod:chrome # Beta 渠道构建CHANNELbeta npm run build:beta:chrome # 监听模式配合浏览器扩展自动重载调试 npm run build:watch:chrome npm run build:watch:firefox # 测试 npm test这些脚本底层通过cross-env注入环境变量后调用webpack例如build:chrome实际执行cross-env BROWSERchrome MANIFEST_VERSION3 NODE_OPTIONS--max-old-space-size8192 webpackNODE_OPTIONS--max-old-space-size8192将 Node 堆上限提升到 8 GB用以应对 Angular 应用在大型 monorepo 中编译时的内存压力这也是在本地首次构建时需要注意的资源前提。打包分发脚本同样齐全例如dist:chrome生产构建 压缩为dist-chrome.zip、dist:firefox:mv3、dist:safari构建后调用scripts/package-safari.ps1走 Safari 专用打包流程。四、Manifest 生成原理一个模板五种浏览器浏览器扩展的身份证是manifest.json。该仓库并没有为每个浏览器各维护一份清单而是通过 apps/browser/webpack/manifest.js 在构建期动态变换。4.1 浏览器前缀覆盖机制transform()函数支持一种简洁的浏览器前缀语法清单中形如__chrome__xxx、__firefox__xxx的键会在构建时按目标浏览器扁平化。例如模板中同时存在{ background: { service_worker: background.js }, __firefox__background: { scripts: [background.js] } }构建 Chrome 时保留background.service_workerMV3 形态构建 Firefox 时则替换为background.scriptsFirefox 兼容形态。transformPrefixes还支持用null值删除非前缀键例如模板中的__firefox__sandbox: null会在 Firefox 产物中移除sandbox配置。4.2 Beta 渠道覆盖机制transformChannel()处理 Beta 渠道差异当CHANNELbeta时apps/browser/webpack/manifest-beta-overrides.json 中的覆盖项会被合并进 Manifest例如将扩展名替换为__MSG_extNameBeta__、标题改为 Bitwarden Beta。从源码注释可以确认Beta 渠道的版本号压印由 apps/browser/scripts/update-manifest-beta.sh 在构建后单独完成。4.3 MV2 与 MV3 的模板差异仓库中同时保留了两份 Manifest 模板apps/browser/src/manifest.jsonMV2与 apps/browser/src/manifest.v3.jsonMV3。两份模板的差异恰好反映了 Web Extension 演进的要点维度MV2manifest.jsonMV3manifest.v3.json后台执行环境background.page常驻 background.htmlpersistent: truebackground.service_worker可随时被浏览器终止工具栏入口browser_actionaction权限模型直接声明webRequestBlocking等新增activeTab、scripting、offscreen、sidePanel等且 Chrome 侧要求minimum_chrome_version: 102.0MV3 模板还针对 Firefox 提供了覆盖项__firefox__background回退到 scripts 形态印证了上文一个模板、多端变换的设计。扩展内提供的侧边栏sidePanel与 overlay 沙盒页面overlay/menu-button.html、overlay/menu-list.html等能力也分别反映在对应的权限与sandbox配置中。五、目录结构与职责划分apps/browser/src 下的目录与整个 monorepo 的领域划分保持一致从源码结构看各目录职责大致如下popup/扩展弹出窗口的 Angular 应用入口main.ts是 webpack 构建主入口含 HTML 模板、SCSS 与 SVG 图标资源background/后台脚本MV3 下即 service workerautofill/自动填充核心是扩展体积最大的模块约 380 个文件负责登录表单、卡片、身份信息的注入与触发content/相关逻辑分布在autofill/与platform/中对应 Manifest 中content_scripts注入的脚本platform/浏览器平台抽象层BrowserApi等跨浏览器 API 封装即在此目录vault/、auth/、admin-console/、billing/、key-management/、tools/与 Web/Desktop 客户端共用的业务领域模块_locales/63 个语言的国际化 JSONsafari/Safari 扩展的 Swift 原生代码、plist 与 Xcode 工程配置约 20 个文件说明 Safari 版本需要原生壳配合。六、跨浏览器开发的硬性规则BrowserApi 抽象层原 README 只概括了Web Extension API这一技术选型而 apps/browser/CLAUDE.md 把选型落地为三条不可违反的工程纪律它们是理解代码库的关键禁止在业务逻辑中直接使用chrome.*或browser.*API必须通过BrowserApi抽象位于apps/browser/src/platform/browser/browser-api.ts。这是 Chrome / Firefox / Safari / Opera 兼容性的基石事件监听必须使用BrowserApi.addListener()而不是原生chrome.*.addListener()。原因在注释中写得很清楚Safari 需要手动清理监听以避免内存泄漏查询当前窗口标签页时必须使用BrowserApi.tabsQueryFirstCurrentWindowForSafari()——Safari 存在 tab 查询缺陷可能错误地返回多个窗口的标签页。在源码中可以看到这些抽象的实际使用面apps/browser/src/platform/badge/badge-browser-api.ts、apps/browser/src/platform/actions/browser-actions.service.ts等文件均引用BrowserApi并通过badge.service.spec.ts等测试对行为进行验证。同文件还强调了 Manifest V3 的运行时约束后台上下文以 service worker 形式运行随时可能被浏览器终止因此不能假设后台页面持久存在跨上下文通信必须依赖消息传递message passing并且 MV3 下chrome.extension.getBackgroundPage()会返回null。七、本地化与质量保障本地化界面文案统一使用__MSG_xxx__占位符如__MSG_extName__由 apps/browser/crowdin.yml 与 Crowdin 平台联动翻译结果落入src/_locales/测试test目标通过nx/jest:jest运行配置见 apps/browser/jest.config.js并配以 apps/browser/test.setup.ts静态检查lint目标使用nx/eslint:lint扫描apps/browser/**/*.ts与*.html。八、本地开发上手建议综合以上源码事实在本地构建 Bitwarden 浏览器扩展的推荐路径是在仓库根目录安装依赖该仓库为 Nx monorepo依赖集中在根package.json进入 apps/browser 目录执行npm run build:watch:chrome启动 Chrome MV3 开发构建监听模式产物位于dist/apps/browser/chrome-dev在 Chrome 的扩展管理页开启开发者模式选择加载已解压的扩展程序指向上述产物目录即可完成加载调试需要调试 Firefox 时改用npm run build:watch:firefox若需验证 MV2 兼容性Firefox 与 Safari 均提供了-mv2变体如build:watch:firefox:mv3对应 MV3firefox-mv2配置对应 MV2提交代码前运行npm test与仓库级 lint 检查。需要注意的是本地首次构建会触发 Angular 全量编译内存占用较高构建脚本已将 Node 堆上限设为 8 GB建议在内存充足的开发机上执行生产分发dist:*系列还会调用scripts/下的压缩与签名脚本属于发布流程日常开发无需执行。结语Bitwarden 浏览器扩展用 Web Extension API 与 Angular 构建了一套覆盖五大浏览器、兼容 MV2/MV3 的工程体系。其核心工程智慧在于模板 构建期变换的 Manifest 生成机制与BrowserApi抽象层前者让清单差异收敛到一个文件后者让业务代码彻底摆脱浏览器私有 API 的耦合。理解这两点就掌握了阅读、修改与构建该扩展的钥匙更深入的行为细节可以直接在 apps/browser 目录与bitwarden_license/bit-browser商业版源码中继续求证。【免费下载链接】clientsBitwarden client apps (web, browser extension, desktop, and cli).项目地址: https://gitcode.com/GitHub_Trending/cl/clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考