> ## 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，就能跳過 clone、安裝與設定。

## 30 秒執行任何 GitHub 上的擴充功能

下面的章節涵蓋兩條路徑。你會了解 Extension.js 把什麼視為專案根目錄，以及它如何解析像「光是輸入範例名稱」這類有歧義的輸入。

## `dev` 如何解析專案

`extension dev` 可接受一個可選的第一個參數。解析方式如下：

* **沒有參數：** 將目前的工作資料夾視為擴充功能專案。
* **本地路徑：** Extension.js 把它當成相對於目前工作資料夾的路徑（例如，你 clone 了某個儲存庫後，使用 `./my-extension` 或 `../samples/page-redder`）。
* **`https://github.com/...` URL：** Extension.js 會把儲存庫（或 tree 路徑）抓取到你的工作資料夾，然後從解壓後的資料夾建置。詳情請參考 [Project detection and inputs](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，或先 clone 後讓 `dev` 指向該路徑。

## 快速執行 Chrome 擴充功能範例

使用 Chrome Extension Samples 儲存庫裡的範例，快速驗證你的設定並熟悉工作流程。

### 選項 A：完整的 GitHub tree URL（建議）

1. 開啟終端機。
2. `cd` 到 clone 或解壓專案應放置的資料夾（通常是一個空資料夾）。
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 把它當成相對於目前工作資料夾的路徑（例如，你 clone 了某個儲存庫後，使用 `./my-extension` 或 `../samples/page-redder`）。
* **`https://github.com/...` URL：** Extension.js 會把儲存庫（或 tree 路徑）抓取到你的工作資料夾，然後從解壓後的資料夾建置。詳情請參考 [Project detection and inputs](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，或先 clone 後讓 `dev` 指向該路徑。

## 先 clone，再用 `dev` 指向本地路徑

當你想要穩定的資料夾結構（而不是一次性試用）時，請 clone 儲存庫並讓 `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，不需額外設定。

### 用完整 URL 搭配 Edge

<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>

### 先 clone，再使用 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>

## 透過 polyfill 在 Edge 中執行 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>

### 先 clone，再使用 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 中未宣告的資產，可進一步瞭解 [Special folders](/docs/features/special-folders)。

## 最佳實務

* **使用 `extension` 套件**，以單一工具鏈建置、執行與打包你的擴充功能。
* **使用 `--browser`** 在開發時鎖定特定瀏覽器。
* **使用 `--polyfill`** 把以 Mozilla 為主的範例改寫成可在 Chromium 系瀏覽器中運作的版本。
* **一次性試用優先用完整 GitHub URL**；想要穩定資料夾結構時，**clone + 本地路徑**。

## 後續步驟

* 繼續閱讀[建立你的第一個擴充功能](/docs/getting-started/create-your-first-extension)。
* 為你偏好的技術棧瀏覽起始[範本](/docs/getting-started/templates)。
* 透過 [dev 指令選項](/docs/commands/dev)鎖定特定瀏覽器與執行檔。