装环境、建项目、跑起来

环境要求

开发 WXT 项目需要三样东西：

1. Node.js（WXT 0.21.4 要求 Node 22 或更高版本）；
2. 包管理器：npm、pnpm、bun、yarn 任选其一；
3. 目标浏览器：Chrome/Chromium 和（或）Firefox。

先验证环境：

node --version
npm --version

创建项目

打开终端，进入你想放项目的目录，执行：

npx wxt@latest init

其他包管理器对应的写法：

pnpm dlx wxt@latest init   # pnpm
bunx wxt@latest init       # bun

命令会进入交互式问答：输入项目名称、选择模板。官方模板有 vanilla（纯 TypeScript）、Vue、React、Svelte、Solid 五种，默认全部使用 TypeScript；想要纯 JavaScript，把文件扩展名改掉即可。

接着安装依赖。装完后会看到 .wxt/ 目录生成——这是 WXT 自动生成的类型与配置文件（来自 wxt prepare），不要手改，也不要提交到 git。

生成的项目长什么样

my-extension/
├── entrypoints/       # 入口点：background.ts、content.ts、popup/ 等
├── public/            # 原样复制的静态资源
├── assets/            # 需要 Vite 处理的资源
├── .wxt/              # WXT 生成的类型与配置（勿改）
├── .output/           # 构建产物（运行 dev/build 后出现）
├── package.json       # 依赖与命令
├── wxt.config.ts      # WXT 主配置
└── tsconfig.json      # TypeScript 配置（继承 .wxt 生成文件）

各目录的职责在 §04 详细展开，这里先混个脸熟。

启动开发模式

npm run dev

WXT 会启动开发服务器，并自动打开一个浏览器窗口，把扩展装进去。改代码时界面自动刷新，这就是 HMR（热更新）。

如果浏览器没有自动加载，可以手动加载：

1. 打开 chrome://extensions；
2. 右上角开启“开发者模式”；
3. 点击“加载已解压的扩展程序”；
4. 选择 .output/chrome-mv3 目录。

Firefox 则打开 about:debugging#/runtime/this-firefox，选择“临时载入附加组件”，再选 .output/firefox-mv2/manifest.json。临时扩展会在 Firefox 关闭后消失。

第一次修改

打开 entrypoints/popup/index.html（或模板对应的组件），改一行文字，保存。浏览器里的扩展界面应立刻更新。

两类文案的更新方式不同，别搞混：

• 扩展自己的 UI 走热更新，改完即见；
• 浏览器持有的扩展名称、描述来自生成的 manifest 和 _locales，可能需要刷新扩展甚至重启浏览器。

常见问题

• 报错说 .wxt/tsconfig.json 不存在：执行 npm run postinstall（即 wxt prepare）重新生成；
• 浏览器没自动打开：确认本机 Chrome/Firefox 安装位置正常，或按 §05 配置浏览器启动；
• 修改代码没反应：确认改的是当前界面实际使用的组件；manifest、后台和内容脚本的改动，通常比普通组件更需要刷新扩展或页面。

装完跑不起来时，八成是 Node 版本或网络问题：先 node -v 确认 ≥ 22，再检查 npm 镜像源是否可用。

遇到「扩展已加载但图标没出现」的情况，先确认 manifest 的 icons 配置和图标文件路径（§23 会讲图标规则）。

小结

项目已经跑起来了：环境就绪、扩展加载、改动热更新。下一节深入项目结构，搞清楚代码到底该放哪儿。