CLI 手册：wxt 主命令

一条命令，七个面孔

WXT 的所有操作都收敛在 wxt 这一条命令上，用子命令区分动作。在项目目录里执行 npx wxt 或 pnpm wxt，就能看到完整清单：

命令	作用	一句话记忆
wxt（不带子命令）	启动开发服务器	等价于 wxt dev
wxt build	生产构建	产出 .output/ 目录
wxt zip	构建并打包 zip	产出商店可上传的压缩包
wxt prepare	生成类型声明与自动导入文件	装完依赖后跑一次
wxt clean	清理生成文件与缓存	出问题时先试它
wxt init	初始化新项目	建项目唯一入口
wxt submit	一键提交到各浏览器商店	发布流水线的最后一环

注意第一条：wxt 后面什么都不跟，默认就是启动开发服务器，等价于 wxt dev。所以命令行的 [root] 参数（项目根目录）对多数命令都可选，默认用当前目录。

全局选项：所有命令都认得

下面这些选项几乎每条命令都支持，属于「全家桶」。个别命令只支持其中一部分，但看到名字就不会认错：

选项	简写	作用
--config <file>	-c	指定配置文件，默认 wxt.config.ts
--mode <mode>	-m	设置环境模式，如 development / production / 自定义
--browser <browser>	-b	指定目标浏览器，如 chrome / firefox / edge
--host <host>	—	开发服务器绑定的主机地址
--port <port>	-p	开发服务器端口
--filter-entrypoint <name>	-e	只构建指定的入口点
--mv3	—	强制生成 MV3 清单
--mv2	—	强制生成 MV2 清单
--debug	—	调试模式，输出更多错误堆栈
--level <level>	—	日志级别，从 silent 到 verbose 共 14 档
--help	-h	查看帮助
--version	-v	查看版本号

选项的作用范围

全局选项虽多，各自管的事不同，别混用：

• --host、--port 只对开发服务器生效，构建时指定会被忽略。
• --filter-entrypoint 作用于 build、zip 这类「产出产物」的命令，用来缩小构建范围；-e 在 dev 模式下的行为官方文档未明确，以 npx wxt --help 实测为准。
• --mv3 与 --mv2 互斥，同时指定会报错。不指定时，WXT 按目标浏览器的默认值决定，Chrome 默认 MV3。
• --mode 影响环境变量与构建模式（§26 有完整讲解），--browser 决定产物目录名（.output/chrome-mv3 这类，§35 详述）。

组合起来看

单个选项好懂，组合起来才见功力。几个高频组合：

# 只构建 Firefox 版，并带上调试信息
npx wxt build -b firefox --debug

# 开发服务器换端口，方便多项目并行
npx wxt dev -p 3000

# 只打包 popup 入口点，加快验证速度
npx wxt build -e popup

# 指定一个自定义模式（配合 §26 的构建模式使用）
npx wxt build -m staging

日志级别怎么选

--level 的值是固定枚举：silent、fatal、error、warn、log、info、success、fail、ready、start、box、debug、trace、verbose，从静默到啰嗦。日常用默认就好；排查诡异问题时 --debug 比调日志级别更省事，它会带上完整的错误堆栈。

和 §05 的分工

§05 讲的「天天用的命令」是日常工作流：dev 开发、build 构建、zip 打包、prepare 生成类型、clean 清理。本节补上了 init（建项目，§03 已用过）和 submit（商店提交，§39 已详述），凑齐完整七条。剩下没讲透的参数，下一节逐个命令展开。

小结

• 七条命令覆盖全流程：init / dev / build / zip / prepare / clean / submit。
• 全局选项 -c、-m、-b、-e、--mv3、--mv2、--debug、--level 高频使用。
• 版本迭代快，选项细节以 npx wxt --help 实测为准。