> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 用 Extension.js 示例立即上手

> 用 Extension.js 在 30 秒内运行任意 GitHub 浏览器扩展。把 GitHub URL 传给 extension dev，跳过克隆、安装与配置。

## 30 秒运行任意 GitHub 上的扩展

下面的小节涵盖了两条路径。你将了解 Extension.js 把什么视为项目根目录，以及它如何解析像裸示例名这样的模糊输入。

## `dev` 如何解析项目

`extension dev` 接受一个可选的首个参数。解析规则如下：

* **无参数：** 将当前工作目录作为扩展项目。
* **本地路径：** Extension.js 将其视为相对于当前工作目录的路径（例如克隆仓库后的 `./my-extension` 或 `../samples/page-redder`）。
* **`https://github.com/...` URL：** Extension.js 会把仓库（或其某个 tree 路径）拉取到你的工作目录，再从抽取出的目录中构建。详见 [项目检测与输入](https://github.com/extension-js/extension.js/blob/main/programs/develop/README.md#project-detection-and-inputs)。
* **其他 `http(s)` URL：** Extension.js 把该 URL 视为一个 ZIP 压缩包，下载并在本地解压。

像 `sample.page-redder` 这样的裸名字 **不会** 触发远程拉取；它只是当前目录下的一个文件夹名。请使用完整的 GitHub URL，或者先克隆然后把 `dev` 指向该路径。

## 快速运行 Chrome 扩展示例

利用 Chrome Extension Samples 仓库中的示例来验证你的环境并快速熟悉工作流。

### 方式 A：完整的 GitHub tree URL（推荐）

1. 打开终端。
2. `cd` 进入用于存放克隆/解压项目的目录（通常是一个空目录）。
3. 运行：

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder
  ```

  ```bash bun theme={null}
  bunx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder
  ```

  ```bash bun theme={null}
  bunx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder
  ```
</CodeGroup>

Extension.js 会拉取示例、构建并启动 Chrome，加载该扩展。你可以在 [Chrome Extension Samples](https://github.com/GoogleChrome/chrome-extensions-samples) 中浏览更多 URL 来尝试。想要针对其他浏览器，在命令后追加 `--browser=firefox` 或 `--browser=edge`。

## `dev` 如何解析项目

`extension dev` 接受一个可选的首个参数。解析规则如下：

* **无参数：** 将当前工作目录作为扩展项目。
* **本地路径：** Extension.js 将其视为相对于当前工作目录的路径（例如克隆仓库后的 `./my-extension` 或 `../samples/page-redder`）。
* **`https://github.com/...` URL：** Extension.js 会把仓库（或其某个 tree 路径）拉取到你的工作目录，再从抽取出的目录中构建。详见 [项目检测与输入](https://github.com/extension-js/extension.js/blob/main/programs/develop/README.md#project-detection-and-inputs)。
* **其他 `http(s)` URL：** Extension.js 把该 URL 视为一个 ZIP 压缩包，下载并在本地解压。

像 `sample.page-redder` 这样的裸名字 **不会** 触发远程拉取，它只是当前目录下的一个文件夹名。请使用完整的 GitHub URL，或者先克隆然后把 `dev` 指向该路径。

## 先克隆，再用 `dev` 指向本地路径

当你希望拥有稳定的目录布局（而不是一次性尝试），可以先克隆仓库，再把 `dev` 指向本地路径：

```bash theme={null}
git clone https://github.com/GoogleChrome/chrome-extensions-samples.git
cd chrome-extensions-samples/functional-samples/sample.page-redder
npx extension@latest dev .
```

<Frame>
  <iframe className="w-full aspect-video rounded-xl" src="https://www.loom.com/embed/34fc48f3f7954bfa990e767c6a7172f0?sid=346f6a11-58d6-48a4-8935-aac8119d765d" title="page-redder sample running with extension dev" loading="lazy" referrerPolicy="no-referrer-when-downgrade" allow="clipboard-write; encrypted-media; fullscreen" allowFullScreen />
</Frame>

在 [Chrome Extension Samples](https://github.com/GoogleChrome/chrome-extensions-samples) 中浏览更多示例。

## 在 Microsoft Edge 中运行示例

Extension.js 支持 Microsoft Edge，无需额外配置。

### Edge 配合完整 URL

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/topSites/magic8ball --browser=edge
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/topSites/magic8ball --browser=edge
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/topSites/magic8ball --browser=edge
  ```

  ```bash bun theme={null}
  bunx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/topSites/magic8ball --browser=edge
  ```

  ```bash bun theme={null}
  bunx extension@latest dev https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/topSites/magic8ball --browser=edge
  ```
</CodeGroup>

### 先克隆，再使用 Edge

```bash theme={null}
git clone https://github.com/GoogleChrome/chrome-extensions-samples.git
cd chrome-extensions-samples/api-samples/topSites/magic8ball
npx extension@latest dev . --browser=edge
```

本示例使用 [magic8ball](https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/topSites/magic8ball) 样例。

<Frame>
  <iframe className="w-full aspect-video rounded-xl" src="https://www.loom.com/embed/284d706379a84adabfdde6bd341b8d24?sid=24a4a6d5-5b30-4920-8a47-004540183aed" title="magic8ball sample running in Microsoft Edge" loading="lazy" referrerPolicy="no-referrer-when-downgrade" allow="clipboard-write; encrypted-media; fullscreen" allowFullScreen />
</Frame>

## 在 Edge 中借助 polyfill 运行 Mozilla 扩展

你可以在 Edge 中运行 MDN WebExtensions 示例。传入 GitHub tree URL 并启用 polyfill（一种兼容层）。该 polyfill 把 Firefox 风格的 `browser.*` 调用映射为 Chrome 风格的 `chrome.*` 调用，从而让你面向 Firefox 编写的扩展也能在基于 Chromium 的浏览器上工作。

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest dev https://github.com/mdn/webextensions-examples/tree/main/apply-css --browser=edge --polyfill=true
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest dev https://github.com/mdn/webextensions-examples/tree/main/apply-css --browser=edge --polyfill=true
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest dev https://github.com/mdn/webextensions-examples/tree/main/apply-css --browser=edge --polyfill=true
  ```

  ```bash bun theme={null}
  bunx extension@latest dev https://github.com/mdn/webextensions-examples/tree/main/apply-css --browser=edge --polyfill=true
  ```

  ```bash bun theme={null}
  bunx extension@latest dev https://github.com/mdn/webextensions-examples/tree/main/apply-css --browser=edge --polyfill=true
  ```
</CodeGroup>

### 先克隆，再使用 polyfill + Edge

```bash theme={null}
git clone https://github.com/mdn/webextensions-examples.git
cd webextensions-examples/apply-css
npx extension@latest dev . --browser=edge --polyfill=true
```

本示例来自 MDN WebExtensions Examples 的 [Apply CSS](https://github.com/mdn/webextensions-examples/tree/main/apply-css) 示例。

<Frame>
  <iframe className="w-full aspect-video rounded-xl" src="https://www.loom.com/embed/6eb724aad822413fb4fe9f52afec5576?sid=e2aa47a4-71d4-4ff1-887a-dcf8031ea917" title="Apply CSS extension running in Edge with polyfill" loading="lazy" referrerPolicy="no-referrer-when-downgrade" allow="clipboard-write; encrypted-media; fullscreen" allowFullScreen />
</Frame>

## 从零创建一个最小扩展

使用 `extension create` 配合 `init` 模板，得到最轻量的起点：一份 manifest 和图标，没有任何框架或 UI 表面。

### `init`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/init/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=a45f4715e415a8775c5122355ed9cf54" alt="init template screenshot" width="2400" height="1800" data-path="images/examples/init/screenshot.png" />

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=init
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=init
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=init
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=init
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=init
  ```
</CodeGroup>

仓库：[extension-js/examples/init](https://github.com/extension-js/examples/tree/main/examples/init)

## 快速提示

* **使用 TypeScript：** 在项目根目录添加 `tsconfig.json` 文件。
* **使用 React：** 在 `package.json` 中添加 `react` 与 `react-dom`。
* 为 React 配置好的 `tsconfig.json` 即可启用 TypeScript + React 编写体验。
* 如果你需要处理 manifest 中未声明的资源，可以了解更多 [特殊文件夹](/docs/features/special-folders) 相关内容。

## 最佳实践

* **使用 `extension` 包**，用同一条工具链构建、运行并打包你的扩展。
* **使用 `--browser`**，在开发时指定目标浏览器。
* **使用 `--polyfill`**，当你把面向 Mozilla 的示例适配到基于 Chromium 的浏览器时。
* **一次性尝试时优先使用完整的 GitHub URL**；**需要稳定的目录布局时则使用克隆 + 本地路径**。

## 下一步

* 继续阅读 [创建你的第一个扩展](/docs/getting-started/create-your-first-extension)。
* 浏览适合你偏好技术栈的入门 [模板](/docs/getting-started/templates)。
* 查看 [dev 命令选项](/docs/commands/dev)，用以指定浏览器和可执行文件。