一步步创建你的第一个浏览器扩展

你将构建一个 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`	按浏览器划分的运行选项，例如配置文件和浏览器 flag。	可选。删除它即可恢复默认值。
`.extension-create.json`	记录 create 的版本、模板与模板 ref。	为溯源保留。构建不会读取它。
`README.md`、`STORE.md`	起步文档和一份商店信息草稿。	替换或删除。
`src/manifest.json`	扩展的 manifest。	就地编辑。不要再加第二份 manifest。
`src/background.js`	sidebar 起步模板的后台脚本。	编辑或替换，就像本教程做的那样。
`src/content/`	起步模板注入到每个页面的 content script。	删除它，并移除它的 `content_scripts` 条目。
`src/sidebar/`	起步模板的 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 脚本运行的是本地的 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"
  }
}

这些脚本就是 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，按下回车。新标签页将打开 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 端到端测试添加自动化检查。
随着扩展的成长，回顾故障排查、安全清单与性能手册。

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 步：让它更好用

下一步