如果你打算为 Chrome、Safari、Firefox、Opera 等浏览器开发扩展程序，很可能在官方文档中见过“WebExtension”这个术语。尽管“WebExtension”和“Chrome 扩展”在某种程度上指的是同一套技术，但在进行跨浏览器扩展开发时，你仍需清楚它们之间的关键差异。

在这篇文章中大眼仔将介绍支撑 Chrome 扩展和 WebExtension 的通用 API 平台，并指出在为多个浏览器开发扩展时可能遇到的一些陷阱。

Google Chrome 扩展

什么是 WebExtension？

Google Chrome 于 2009 年首次引入浏览器扩展支持，这项功能迅速成为 Chrome 成功的关键因素之一。这些扩展构建起来极其简单（尤其对熟悉 JavaScript 和 Web 开发的开发者而言）而且不会因 Chrome 更新而失效。直到 2013 年，Google 强制推行 Manifest V2，才首次对扩展 API 做出重大且破坏性的变更。

随后，许多其他浏览器开始采用 Chrome 的技术基础（更准确地说，是 Chromium 引擎），并沿用了相同的扩展 API。因此，为 Chrome 编写的扩展通常无需修改即可在 Opera、Vivaldi、Brave、Microsoft Edge、ChatGPT Atlas 等基于 Chromium 的浏览器上直接运行。其中大多数甚至可以直接从 Google 的 Chrome 网上应用店安装扩展，尽管 Opera 和 Edge 等浏览器也维护着自己的扩展商店。

Mozilla 则从 2015 年起逐步将 Firefox 转向 Chrome 的扩展 API。此前 Firefox 使用的是基于 XUL 的扩展系统，复杂且极易因浏览器更新而崩溃。由于 Firefox 并非基于 Chromium，Mozilla 不得不反向工程整套 API。这一新实现被称作 “WebExtensions”，其初衷正是建立一个跨浏览器的扩展标准。

Apple 也为 Safari 浏览器反向实现了 Chromium 的扩展 API，并沿用了 Mozilla 提出的 “WebExtension” 这一名称。但需要注意的是，Apple 的实现与 Mozilla 或 Chromium 中的 API 并不完全一致。

表面上看，WebExtension 似乎已成为统一标准，但实际上它的碎片化程度远高于现代 Web 开发。这更像是 2000 年代的 Web 开发环境 —— 各浏览器的 API 和渲染能力差异巨大（再见了，IE 专属样式表）。用《加勒比海盗》中巴博萨船长的话来说：“这些代码更像是指导方针，而非真正的规则。”

WebExtension 与 Chrome 扩展的区别

WebExtension 与普通 Chrome 扩展的主要区别在于：你必须考虑不同浏览器的行为差异，并确保所使用的 API 在目标浏览器中均受支持。对此，MDN（Mozilla Developer Network）是最权威的信息来源 —— 每个 API 页面都包含详细的浏览器兼容性表格和跨浏览器支持说明。

当你为 Chrome 构建一个现代网站时，通常无需修改就能在 Firefox 和 Safari 上正常运行，因为浏览器厂商会通过 W3C 等组织共同制定 Web 标准（如 Interop 项目）。但扩展开发并非如此。虽然 Google 也参与了 WebExtensions 社区的部分工作，但新的 Chromium API 往往需要很长时间才会出现在 Firefox 或 Safari 中（有些甚至永远不会出现），而且每个浏览器都有其独有的专属功能。

举例说明：

sidebarAction API 最初由 Opera 引入，用于让扩展在侧边栏显示页面。Firefox 后来复制了这一功能，使得侧边栏扩展可在 Opera 和 Firefox 上使用，但 Chrome 并不支持。当 Google 最终在 Chrome 中加入侧边栏时，却创建了一个全新的 sidePanel API。截至 2025 年底，Firefox 尚未实现 sidePanel API，而 Safari 则两种都不支持。

1
2
3
4
// Showing a welcome page in Chrome’s default API namespace

chrome.tabs.create({ 'url': chrome.runtime.getURL('welcome.html') });

// Showing a welcome page in WebExtension ‘browser’ namespace

browswer.tabs.create({ 'url': chrome.runtime.getURL('welcome.html') });

另一个重要区别是 命名空间（namespace）。在 Chromium 的扩展 API 中，大多数函数以 chrome 开头，例如 chrome.storage 或 chrome.windows。而在 WebExtension 的大多数文档中，你会看到使用 browser 命名空间，例如 browser.storage。

Firefox 和 Safari 都将 chrome 作为 browser 的别名（针对源自 Chrome 的 API），但 Chrome 完全不识别 browser 命名空间。

如何开发跨浏览器扩展？

跨浏览器扩展开发的最佳实践与 Web 开发类似：你必须在每一个目标浏览器上测试你的扩展 —— 几乎可以肯定，某些功能在不同浏览器中的表现会有所不同。

建议构建一套测试套件，在整个开发过程中多次运行。一旦发现兼容性问题，应使用 特性检测（feature detection） 而非 浏览器嗅探（browser sniffing） 来调整行为。

1
2
3
4
5
6
7
8
9
10
11
12
13
// This could be checked with feature detection:

if ("bubble" in chrome) {

console.log("API is available!");

} else {

console.error("API is not available!");

}



// Do NOT do a browser check like this:

if (navigator.userAgent.includes("Firefox")) {

console.error("API is not available!");

} else {

console.log("API is available!");

}

好消息是，主流浏览器（Windows、macOS 和桌面 Linux）基本都支持多平台安装，因此安装多个浏览器用于测试几乎零成本（只需占用一些存储空间）。唯一的例外是 Safari，开发 Safari 扩展必须使用 Mac 电脑并安装 Xcode。

此外，你还需要决定在整个代码中使用哪个命名空间：chrome（如 chrome.storage）还是 browser（如 browser.storage）。我个人倾向于统一使用 chrome 命名空间；当然，你也可以借助 Mozilla 提供的 polyfill 库，让 Chrome 支持 browser 命名空间。像 uBlock Origin 这样的项目则会自行封装一层，自动适配当前可用的命名空间。

若想了解跨浏览器扩展开发中的常见问题，可查阅 MDN 的 Chrome 不兼容性页面。截至 2025 年底，大多数问题集中在 Manifest V3 引入的新 API 或清单字段上。

发布扩展时的注意事项

发布扩展时，并非必须为每个浏览器单独提交到各自的商店。Chrome 网上应用店不仅限于 Chrome 用户，Opera、Vivaldi 和 Edge 用户同样可以从该平台安装和更新扩展。不过，在各个浏览器的官方商店发布能显著提升曝光度。例如，Microsoft Edge 会引导用户前往 Edge 外接程序网站下载扩展，而非 Chrome 应用店；而 Firefox 和 Safari 用户则无法直接从 Chrome 应用店安装扩展。

总结

尽管 WebExtension 文档可能让人误以为跨浏览器扩展开发轻而易举，实际情况虽不复杂，但也绝非毫无挑战。多数扩展只需对 manifest 文件和代码库做少量调整，即可在多个浏览器上运行，且并不强制要求在每个商店都发布。最大的额外成本在于测试时间，因为你无法像对待普通网站或 Web 应用那样，对扩展的跨浏览器兼容性做出乐观假设。

正因如此，理解 WebExtension 与 Chrome 扩展之间的微妙差异，是打造真正跨平台浏览器扩展的第一步。