Back

如何构建你的第一个 Firefox 扩展

OpenReplay Team OpenReplay Team

Nov 14, 2025 · 3 min read

如何构建你的第一个 Firefox 扩展

构建 Firefox 扩展可能看起来令人生畏,但借助 Manifest V3 和现代 WebExtensions API,你可以在 10 分钟内创建第一个可工作的扩展。本 Firefox 扩展教程将引导你创建一个功能完整的 MV3 扩展,它可以修改网页并包含弹出界面。

核心要点

  • 使用 Manifest V3 在 10 分钟内创建可工作的 Firefox 扩展
  • 构建在隔离上下文中安全修改网页的内容脚本
  • 实现用于用户交互的弹出界面与消息传递机制
  • 遵循最小权限和外部脚本的安全最佳实践

什么是 WebExtensions?为什么选择 Manifest V3?

WebExtensions 是使用标准 Web 技术(HTML、CSS 和 JavaScript)构建的跨浏览器兼容附加组件。Firefox WebExtensions Manifest V3 代表了扩展开发的当前标准,通过 service workers 提供改进的安全性,通过声明式 API 提供更好的性能,以及更强的跨浏览器兼容性。

虽然 Firefox 仍然支持 Manifest V2,但从 Manifest V3 开始可以确保你的扩展与未来的浏览器更新保持兼容,并与 Chrome、Edge 和 Safari 的扩展架构保持一致。本指南专注于 MV3 最佳实践。

设置你的 Firefox 扩展项目结构

让我们一步步构建你的第一个 Firefox 扩展。创建一个名为 my-first-extension 的新文件夹,并添加以下必需文件:

创建 Manifest V3 配置

manifest.json 文件是任何扩展的核心。使用以下 Manifest V3 配置创建此文件:

{
  "manifest_version": 3,
  "name": "My Page Enhancer",
  "version": "1.0.0",
  "description": "Enhances web pages with custom styling",
  
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "48": "icon.png"
    }
  },
  
  "content_scripts": [
    {
      "matches": ["*://*.example.com/*"],
      "js": ["content.js"]
    }
  ],
  
  "icons": {
    "48": "icon.png"
  }
}

注意使用 "action" 而不是已弃用的 "browser_action"——这是 Firefox MV3 的关键要求。该清单遵循最小权限原则,这是 Firefox 扩展的核心最佳实践。

构建用于页面修改的内容脚本

MV3 内容脚本在隔离的上下文中运行,保护你的扩展代码免受恶意页面脚本的影响。创建 content.js:

// content.js - Runs on matching pages
console.log('Extension loaded on:', window.location.href);

// Add a subtle border to all paragraphs
document.querySelectorAll('p').forEach(paragraph => {
  paragraph.style.border = '2px solid #4A90E2';
  paragraph.style.padding = '8px';
  paragraph.style.borderRadius = '4px';
});

// Listen for messages from the popup
browser.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === 'changeColor') {
    document.body.style.backgroundColor = request.color;
  }
});

这演示了 Manifest V3 如何将扩展代码与页面上下文隔离,防止旧扩展架构中常见的安全漏洞。

创建 Firefox Action 弹出界面

action 弹出组件提供用户交互功能。创建 popup.html:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    body { 
      width: 300px; 
      padding: 16px;
      font-family: system-ui, -apple-system, sans-serif;
    }
    button { 
      width: 100%; 
      padding: 8px; 
      margin: 4px 0;
      cursor: pointer;
    }
  </style>
</head>
<body>
  <h2>Page Enhancer</h2>
  <button id="blue">Blue Background</button>
  <button id="green">Green Background</button>
  <script src="popup.js"></script>
</body>
</html>

添加相应的 popup.js 来处理用户交互:

// popup.js - Handles popup interactions
document.getElementById('blue').addEventListener('click', () => {
  sendColorChange('#E3F2FD');
});

document.getElementById('green').addEventListener('click', () => {
  sendColorChange('#E8F5E9');
});

async function sendColorChange(color) {
  const [tab] = await browser.tabs.query({
    active: true,
    currentWindow: true
  });
  
  browser.tabs.sendMessage(tab.id, {
    action: 'changeColor',
    color: color
  });
}

加载和测试你的 JavaScript Firefox 附加组件

要测试你的 JavaScript Firefox 附加组件:

  1. 打开 Firefox 并导航到 about:debugging
  2. 点击左侧边栏中的”此 Firefox”
  3. 点击”加载临时附加组件”
  4. 从扩展文件夹中选择任意文件

你的扩展图标会出现在工具栏中。访问任何 example.com 页面以查看内容脚本的实际效果。点击扩展图标打开弹出窗口并测试背景颜色更改。

当你修改文件时,在 about:debugging 中点击”重新加载”即可立即应用更改——无需重启浏览器。

MV3 开发的 Firefox 扩展最佳实践

遵循这些 Firefox 扩展最佳实践可确保你的扩展通过审核并提供安全的用户体验:

  • 最小权限:仅在需要访问当前标签页时请求 activeTab,避免广泛的主机权限
  • 禁止内联 JavaScript:MV3 的内容安全策略会阻止内联脚本——始终使用外部 .js 文件
  • Service Workers:对于后台任务,使用 service workers(此处未涵盖,但对高级功能至关重要)
  • 安全通信:使用 browser.runtime.sendMessage() 进行组件间通信

结论

你已经成功使用 Manifest V3 构建了一个可工作的 Firefox 扩展。从简单的内容脚本过渡到功能完整的扩展遵循相同的模式:隔离上下文、消息传递和最小权限。掌握这些基础知识,你将能够构建用户信任的安全、高性能扩展。

要扩展你的技能,请探索 Storage API 以持久化用户偏好,实现后台 service workers 以处理复杂事件,并查看最新的 MDN WebExtensions 文档了解 API 更新。

常见问题

可以,使用 Manifest V3 的 WebExtensions 在各浏览器之间基本兼容。API 命名空间存在细微差异,Chrome 使用 chrome 而 Firefox 使用 browser,但 Firefox 为了兼容性同时支持两者。

manifest.json 文件在 content_scripts 部分指定了匹配模式。更改 matches 数组以包含其他域名,或使用更广泛的模式如 *://*/* 匹配所有站点,但这需要仔细考虑安全性。

将扩展打包为 ZIP 文件,在 addons.mozilla.org 上创建开发者账户,提交扩展进行审核,然后等待批准。Firefox 通常在 24-48 小时内审核扩展。

内容脚本在网页上下文中运行,可以访问和修改 DOM 元素。MV3 中的后台脚本使用 service workers 处理事件和 API 调用,但不能直接访问页面内容,需要通过消息传递进行通信。

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.

OpenReplay

More articles from OpenReplay Blog