构建模式与运行时配置

第 05 章讲过 wxt dev 和 wxt build 的用法，这一章换到配置视角：模式（mode）如何决定构建行为，运行时配置（runtime config）又该放在哪里。

构建模式：开发与生产的开关

WXT 底层由 Vite 驱动，因此完整继承了 Vite 的模式（mode）机制。执行命令时用 --mode 指定：

wxt --mode production
wxt build --mode development
wxt zip --mode testing

默认值是：dev 命令用 development，其余命令（build、zip 等）用 production。所以不传 --mode 时，开发构建和生产构建天然走不同模式。除了这两个，你也可以传 testing、staging 等自定义模式，给不同环境开不同开关。

在配置里读模式

wxt.config.ts 本身可以导出函数，接收一个包含命令信息的参数对象：

export default defineConfig(({ command, mode, browser, manifestVersion }) => {
  // command: 'dev' | 'build' | 'zip' | ...
  // mode: 'development' | 'production' | 自定义值
  return {
    // ...
  };
});

这样就能按命令或模式切换配置：比如 zip 命令时才开启某个模块，development 模式下给清单加调试标记。上一章的 manifest 函数也能拿到 mode，两者配合，几乎任何构建期决策都能按模式定制。

在代码里读模式

构建模式会以 import.meta.env.MODE 的形式暴露给扩展代码，运行时随时可以读取：

switch (import.meta.env.MODE) {
  case 'development':
    // 开发环境逻辑
    break;
  case 'production':
    // 生产环境逻辑
    break;
  case 'testing': // 自定义模式
  case 'staging':
    // ...
    break;
}

运行时配置：app.config.ts

构建期配置放在 wxt.config.ts，那「运行时也要用、但不想每次写死」的配置放哪？答案是 <srcDir>/app.config.ts。它在单个文件里集中定义运行时配置：

import { defineAppConfig } from '#imports';

// 先扩展类型，让 theme 字段可被识别
declare module 'wxt/utils/define-app-config' {
  export interface WxtAppConfig {
    theme?: 'light' | 'dark';
  }
}

export default defineAppConfig({
  theme: 'dark',
});

任何代码里都能通过 getAppConfig 读取：

import { getAppConfig } from '#imports';

console.log(getAppConfig()); // { theme: "dark" }

环境变量进运行时配置

app.config.ts 里可以用环境变量，这是它的主要价值之一：

declare module 'wxt/utils/define-app-config' {
  export interface WxtAppConfig {
    apiKey?: string;
    skipWelcome: boolean;
  }
}

export default defineAppConfig({
  apiKey: import.meta.env.WXT_API_KEY,
  skipWelcome: import.meta.env.WXT_SKIP_WELCOME === 'true',
});

这样做的三个好处：

1. 所有预期的环境变量集中在一个文件里声明，一目了然
2. 可以把字符串转换成布尔、数组等类型，skipWelcome 从 "true" 变成 true
3. 环境变量缺失时可以给默认值

构建期与运行期的分工

把两种配置放在一起看，分工就清楚了：

• 构建期配置（wxt.config.ts）：影响「怎么构建」——目标浏览器、清单内容、Vite 插件、模块开关
• 运行时配置（app.config.ts）：影响「运行表现」——主题、功能开关、API 地址这类扩展内要读的值

生产项目还会给环境变量加一层校验。比如 mkext 用第三方库 envin 配合 zod，在配置里声明每个变量的格式和默认值，构建时校验失败直接报错。注意 envin 不是 WXT 自带的能力，属于工程实践，需要时自行引入。

小结

• development / production 与自定义 mode 影响环境变量与产物形态。
• 构建期配置用 defineConfig(({ command, mode }) => ...)，运行时配置走 app.config.ts。
• 配置里判断环境用函数参数 mode，import.meta.env.DEV 在配置文件里是未定义的。