逐步建立你的第一個瀏覽器擴充功能

你將建立一個 Omnibox（網址列）捷徑。在網址列輸入 gh、再輸入查詢字串，就會直接前往 GitHub 搜尋結果。過程中你會串接一份 manifest.json，並在背景 service worker 中處理輸入。同時也會熟悉每個專案都會遵循的開發循環（create → dev → build）。

你會做出什麼

能力	你會獲得的成果
Omnibox 關鍵字流程	在瀏覽器網址列輸入 `gh` 觸發擴充功能行為
背景事件處理	透過 service worker 處理使用者輸入
本地開發循環	快速執行、載入並驗證擴充功能行為
漸進式強化	在基本流程運作後加入即時的 GitHub 搜尋建議

計畫

讓 GitHub 搜尋速度像瀏覽器原生捷徑一樣快。擴充功能會保留關鍵字 gh；當你輸入 gh 加上查詢字串後，會打開 GitHub 的搜尋結果。

步驟 1：建立擴充功能

使用 Extension.js 的 create 指令來建立一個名為 github-search 的擴充功能。預設範本是一個可直接運作的 sidebar 起始範本，因此建立出來的專案已經包含 src/manifest.json 與 src/background.js。接下來兩個步驟會取代這兩個檔案。本教學中你寫的所有內容都放在 src/ 底下，因為只要 src/manifest.json 存在， Extension.js 就會優先採用它。

正在使用 Yarn？ yarn dlx 指令需要 Yarn 2 或更新版本。Yarn 1 沒有 dlx，會以「Command not found」錯誤失敗。在 Yarn 1 上，請改用 npm 分頁（npx）。

npx extension@latest create github-search

pnpx extension@latest create github-search

yarn dlx extension@latest create github-search

bunx extension@latest create github-search

deno run -A npm:extension@latest create github-search

正在使用 Deno？ Deno 會非常積極地快取 npm 套件，包括 @latest 標籤，因此 npm:extension@latest 可能一直解析到較舊的快取版本。如果建立專案或 dev 建置失敗，而該錯誤在較新版本中已經修好（例如 manifest.json references files that were not emitted to disk），請固定版本或重新整理快取：

deno run -A --reload npm:extension@latest create github-search
# or pin an exact version
deno run -A npm:extension@4.1.3 create github-search

執行 deno install 之後，先確認解析出的版本（extension 應與最新發行版本相符），再執行 deno task dev。

create 會產生什麼

create 會建立一個完整的專案，並初始化一個 git 儲存庫。預設範本會產生這棵目錄樹：

github-search/
├── .extension-create.json
├── .gitignore
├── README.md
├── STORE.md
├── extension.config.js
├── package.json
└── src/
    ├── manifest.json
    ├── background.js
    ├── content/
    │   ├── ContentApp.js
    │   ├── scripts.js
    │   └── styles.css
    ├── images/
    │   └── icon.png
    └── sidebar/
        ├── SidebarApp.js
        ├── index.html
        ├── scripts.js
        └── styles.css

TypeScript 與 React 範本會多出 tsconfig.json 與 extension-env.d.ts，提供型別化的擴充功能 API。有兩個檔案定住整個版面：

package.json 標記專案根目錄。特殊資料夾（pages/、scripts/、public/）與 dist/ 輸出都從那個目錄解析，絕不從 src/。
manifest.json 標記擴充功能原始碼。它可以放在根目錄或 src/。兩者都存在時，src/manifest.json 獲勝。

改造骨架時，什麼該編輯、什麼該刪除：

檔案	這是什麼	編輯還是刪除？
`package.json`	專案根目錄標記、腳本，以及固定版本的 `extension`。	保留。編輯名稱與描述。
`extension.config.js`	各瀏覽器的執行選項，例如設定檔與瀏覽器旗標。	可選。刪除它就恢復預設值。
`.extension-create.json`	記錄 create 版本、範本與範本 ref。	為了溯源保留。建置不會讀取它。
`README.md`、`STORE.md`	起始文件與商店上架草稿。	取代或刪除。
`src/manifest.json`	擴充功能的 manifest。	就地編輯。不要再加第二份 manifest。
`src/background.js`	sidebar 起始範本的 background script。	編輯或取代，本教學就是這麼做。
`src/content/`	起始範本注入到每個頁面的 content script。	刪除它，並移除它的 `content_scripts` 項目。
`src/sidebar/`	起始範本的側邊欄面板頁面。	刪除它，並移除它的 `side_panel` 項目。
`src/images/`	manifest 引用的圖示。	保留。換成你自己的圖示。

步驟 2：建立 manifest 檔案

每個擴充功能都從 manifest 檔案開始。它定義中繼資料、權限與執行階段檔案。根據上述計畫，設定 gh 捷徑並加入處理使用者事件的 service worker。打開建立出來的 src/manifest.json，把內容換成：

{
  "manifest_version": 3,
  "name": "GitHub Search",
  "version": "1.0",
  "omnibox": { "keyword": "gh" },
  "background": {
    "service_worker": "service_worker.js"
  }
}

omnibox.keyword：當你輸入 gh 時，瀏覽器會觸發事件。
background.service_worker：監聽你觸發的事件。

步驟 3：建立背景 service worker

在瀏覽器擴充功能中，背景 service worker（一個獨立於任何可見頁面執行的腳本）負責處理瀏覽器事件。在這個範例中，加入一段腳本來監聽 Omnibox 輸入，並把查詢字串導向 GitHub 搜尋。建立 src/service_worker.js，並刪除範本附帶的 src/background.js，這樣就不會有其他檔案占用 background 進入點：

// When the user has accepted what is typed into the omnibox.
chrome.omnibox.onInputEntered.addListener((text) => {
  // Convert any special character (spaces, &, ?, etc)
  // into a valid character for the URL format.
  const encodedSearchText = encodeURIComponent(text);
  const url = `https://github.com/search?q=${encodedSearchText}&type=issues`;

  chrome.tabs.create({ url });
});

上面這段腳本會在你於網址列輸入「gh」之後再輸入任何內容時，開啟一個顯示 GitHub 搜尋結果的新分頁。

步驟 4：載入你的擴充功能

進入專案並安裝相依套件。create 只會建立專案，不會替你安裝，而 dev script 執行的是本地的 extension 執行檔：

cd github-search
npm install

你的 package.json 檔案現在看起來像這樣，其中 extension 固定在你建立專案時使用的版本：

{
  "private": true,
  "name": "github-search",
  "description": "Adds a sidebar panel to the browser with a simple page.",
  "version": "1.0.0",
  "license": "MIT",
  "type": "module",
  "scripts": {
    "dev": "extension dev",
    "start": "extension start",
    "build": "extension build",
    "preview": "extension preview",
    "build:chrome": "extension build --browser chrome",
    "build:firefox": "extension build --browser firefox",
    "build:edge": "extension build --browser edge"
  },
  "dependencies": {},
  "devDependencies": {
    "extension": "^4.1.3"
  }
}

這些 script 是 Extension.js 預設的指令。第一次執行擴充功能：

npm run dev

pnpm run dev

yarn run dev

bun run dev

deno task dev

如果設定正確，Extension.js 會啟動使用全新設定檔的 Chrome、以未封裝擴充功能的方式載入 github-search，並在終端機印出就緒訊息。Chrome 的網址列現在已認得 gh 為關鍵字。輸入 gh 接著按一下空白鍵，輸入 extension.js，按下 Enter。會開啟新分頁前往 https://github.com/search?q=extension.js&type=issues。你現在有一個可以搜尋 GitHub 的可運作擴充功能了。

步驟 5：讓它變得更好

透過 Omnibox 輸入監聽器，在網址列直接顯示建議，藉此改善搜尋體驗。更新 service_worker.js，在輸入時抓取 GitHub 建議並顯示出來。

service_worker.js

// Create a debounce function to avoid excessive
// calls to the GitHub API while the user is still
// typing the search query.
function debounce(fn, delay) {
  let timeoutID;
  return function (...args) {
    if (timeoutID) clearTimeout(timeoutID);
    timeoutID = setTimeout(() => fn(...args), delay);
  };
}

// When the user has changed what is typed into the omnibox.
chrome.omnibox.onInputChanged.addListener(
  debounce(async (text, suggest) => {
    const response = await fetch(
      `https://api.github.com/search/issues?q=${text}`,
    );
    const data = await response.json();
    const suggestions = data.items.map((issue) => ({
      content: issue.html_url,
      description: issue.title,
    }));

    suggest(suggestions);
  }, 250),
);

// When the user has accepted what is typed into the omnibox.
chrome.omnibox.onInputEntered.addListener((text) => {
  // Convert any special character (spaces, &, ?, etc)
  // into a valid character for the URL format.
  const encodedSearchText = encodeURIComponent(text);
  const url = `https://github.com/search?q=${encodedSearchText}&type=issues`;

  chrome.tabs.create({ url });
});

這段程式碼會在網址列直接加入即時的 GitHub 建議。你現在有一個可運作的 GitHub 搜尋擴充功能。繼續迭代，調整成符合自己工作流程的版本。

後續步驟

用範本再建立一個擴充功能。
用 Playwright E2E 加入自動化檢查。
隨著擴充功能成長，瀏覽疑難排解、安全檢查清單與效能手冊。

Introduction

Browser extension fundamentals

Getting started

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

逐步建立你的第一個瀏覽器擴充功能

你會做出什麼

計畫

步驟 1：建立擴充功能

create 會產生什麼

步驟 2：建立 manifest 檔案

步驟 3：建立背景 service worker

步驟 4：載入你的擴充功能

步驟 5：讓它變得更好

後續步驟

​你會做出什麼

​計畫

​步驟 1：建立擴充功能

​create 會產生什麼

​步驟 2：建立 manifest 檔案

​步驟 3：建立背景 service worker

​步驟 4：載入你的擴充功能

​步驟 5：讓它變得更好

​後續步驟

你會做出什麼

計畫

步驟 1：建立擴充功能

create 會產生什麼

步驟 2：建立 manifest 檔案

步驟 3：建立背景 service worker

步驟 4：載入你的擴充功能

步驟 5：讓它變得更好

後續步驟