extension.js

英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

Extension.js [][npm-版本-网址] [][npm-下载-网址] [][操作-网址] [][discord-网址] [][最佳实践-网址]

跨浏览器扩展框架。为 Chrome、Edge、Firefox 和 Safari 构建，无需构建配置。

npx extension@latest create my-extension
cd my-extension
npm run dev

可与 npm、pnpm、yarn、bun 和 deno 一起使用。

CLI 本身可在 Node.js 22.12、Deno 2.5 和 Bun 1.2 上运行。

文档 · 示例 · YouTube · 展示 · 博客

为什么选择 Extension.js

浏览器扩展在现代网页开发中提供了最差的开发体验。Manifest V3 碎片化、浏览器特定的怪癖、内容脚本无法热重载，以及每个目标需要单独的构建流程。Extension.js 解决了这些问题。

• 热模块替换 支持 popup、options、devtools 及其他扩展页面，包括 React、Vue、Svelte 和 Preact 组件，对内容脚本和服务工作者进行有针对性的重载，因此一次保存不会重载整个扩展。
• 默认使用 Manifest V3，为 Chrome、Edge、Firefox 和 Safari 目标提供自动适配器。
• 一条 CLI 可适用于 Chrome、Edge、Firefox 以及任何 Chromium 或 Gecko 二进制。
• 零配置，无需 webpack、rollup 或维护任何插件。
• 一流的 TypeScript、React、Vue、Svelte 和 Preact 支持。
• 生产构建 可用 extension build --zip，为 Chrome 网上应用店和 Firefox 附加组件准备就绪。
• 即插即用，通过一个 devDependency 即可支持现有扩展。

观看它的工作

这有什么不同

如果你使用过 Plasmo、WXT 或 CRXJS，这里是 Extension.js 所做的，而其他工具没有做到的：

框架

浏览器

在使用 extension dev、extension start 或 extension preview 时使用这些标志：

• 选择浏览器：--browser <chrome | edge | firefox | safari>
• 自定义 Chromium 二进制文件：--chromium-binary <path-to-binary>
• 自定义 Gecko（Firefox）二进制文件：--gecko-binary <path-to-binary>

# Chrome (system default)
npx extension@latest dev --browser=chrome

# Edge
npx extension@latest dev --browser=edge

# Custom Chrome/Chromium path
npx extension@latest dev --chromium-binary "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# Custom Firefox path
npx extension@latest dev --gecko-binary "/Applications/Firefox.app/Contents/MacOS/firefox"

发布到商店

构建一个可用于生产的包并将其压缩，以便提交到 Chrome 网上应用店、Edge 附加组件或 Firefox AMO：

# Production build
npx extension@latest build

# Production build packaged as a ZIP
npx extension@latest build --zip

# Per-browser builds
npx extension@latest build --browser=firefox --zip

有用的标志：

• --zip 将构建打包为可上传到商店的 ZIP 文件
• --zip-source 包含用于商店源码审核的源文件
• --zip-filename <name> 控制输出文件名，写为 dist/<name>-<browser>.zip
• --out-dir <path> 将构建写入 <path>/<browser> 而不是 dist/<browser>。拒绝将构建输出到直播开发会话提供的文件夹，因此这是构建与开发会话并行运行的方法
• --polyfill 启用跨浏览器 webextension 填充

管理浏览器二进制文件

跳过系统安装步骤。Extension.js 可以下载并管理隔离的浏览器二进制文件，以进行干净的开发会话：

# Install a managed Firefox build
npx extension@latest install firefox

# Install Chrome and Edge in one go
npx extension@latest install --browser=all

# Print where managed browsers live
npx extension@latest install --where

添加到现有扩展

将 Extension.js 安装为开发依赖并连接你的脚本。

npm install extension@latest --save-dev

{
  "scripts": {
    "build": "extension build",
    "dev": "extension dev",
    "preview": "extension preview"
  }
}

运行 npm run dev 进行开发，并查看浏览器自动打开且已加载你的扩展：

使用 npm run build 用于生产环境，使用 npm run preview 检查生产输出。

从 Chrome 示例开始

从 Chrome Extension Samples 拉取任何示例并直接运行：

npx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder --browser=edge

包管理器

将 Extension.js 添加到项目中，或者在不安装的情况下使用你已经使用的包管理器运行一次。

CLI 所使用的运行时是另一个问题，下面将进行解答。

运行时

社区

• 如果 Extension.js 帮助你更快完成项目，请给仓库加星
• 加入 Discord 获取帮助和反馈
• 在 GitHub 提交问题和功能请求
• 浏览生产就绪的 示例

贡献

欢迎提交错误报告和拉取请求。请阅读 docs/CONTRIBUTING.md 了解开发环境设置、测试命令以及拉取请求需要包含的内容。

许可证

MIT (c) Cezar Augusto and Extension.js 作者。