天天用的命令：dev / build / zip

五个命令一张表

命令	作用
wxt（dev）	启动开发服务器，HMR 热更新，自动打开浏览器并加载扩展
wxt build	生产构建，生成可加载的产物目录
wxt zip	构建并打包商店上传用的压缩包
wxt prepare	生成 TypeScript 项目文件（.wxt/tsconfig.json 等）
wxt clean	清理生成文件与缓存

推荐把它们写进 package.json：

{
  "scripts": {
    "dev": "wxt",
    "dev:firefox": "wxt -b firefox",
    "build": "wxt build",
    "zip": "wxt zip",
    "postinstall": "wxt prepare"
  }
}

postinstall 让每次安装依赖后自动跑 prepare。新手最常踩的“找不到 .wxt/tsconfig.json”就是这么解决的。

dev：开发模式

npm run dev

它做的事：启动 Vite 开发服务器；自动打开浏览器并装好扩展；代码改动即时生效。UI 走 HMR，内容脚本和后台的改动通常刷新扩展或页面即可看到。默认目标浏览器是 Chrome，-b firefox 可切换 Firefox，Edge 同理。

build 与 zip：产物在哪

npm run build
npm run zip

• build 生成可加载目录，默认在 .output/{浏览器}-{manifest版本}/，例如 .output/chrome-mv3/。手动加载扩展时选这个目录；
• zip 先 build 再压缩，产物是商店上传用的 zip；Firefox 还会额外生成源码包（sources zip）。

有的项目把 build:chrome、build:firefox 脚本名做成双浏览器构建，实际执行的还是 wxt zip 或 wxt build -b <浏览器>。看别人项目时，先翻 package.json 确认脚本到底调了什么。

只想构建某几个入口时，可用 -e 指定：

npx wxt build -e popup -e background

prepare 与 clean：维护型命令

npx wxt prepare
npx wxt clean

prepare 生成 .wxt/ 下的类型与配置，改完 tsconfig 或装了新依赖后可以手动跑。clean 清掉 .output/、.wxt/ 等生成物与缓存，遇到诡异构建问题，先 clean 再 build 常能解决。

构建模式：development 与 production

WXT 基于 Vite，支持模式（mode）概念：

• dev 命令默认 development 模式；
• build、zip 等命令默认 production 模式；
• 可用 --mode 覆盖，比如 wxt build --mode development，或自定义 wxt zip --mode testing。

运行时用 import.meta.env.MODE 读取当前模式，代码里可以据此区分环境：

if (import.meta.env.MODE === 'development') {
  // 开发专用逻辑
}

开发时浏览器怎么开

dev 模式默认用 web-ext 自动打开浏览器：装好扩展，使用独立的配置目录，不碰你日常的浏览器资料。启动行为可在三个地方配置：

1. web-ext.config.ts（本机专用，不提交 git）；
2. wxt.config.ts 的 webExt 字段（随仓库走）；
3. 用户目录下的 $HOME/web-ext.config.ts（全局默认）。

常用配置：指定浏览器可执行文件路径、保留开发配置数据、禁用自动开浏览器：

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  binaries: {
    chrome: '/path/to/chrome-beta', // 非标准安装位置时手动指定
    firefox: 'firefoxdeveloperedition',
  },
  chromiumArgs: ['--user-data-dir=./.wxt/chrome-data'], // 保留登录态等数据
  disabled: true, // 不自动开浏览器，用日常配置手动加载
});

改配置不生效、类型死活不更新、产物诡异时，先 wxt clean 再重跑，能治好一半的玄学问题（§42 会细讲）。

小结

五个命令覆盖“开发—构建—打包—维护”全流程，模式与浏览器启动配置让开发环境可调可控。下一节揭开黑盒：WXT 背后到底干了啥。