WXT 中文文档

Appearance

浏览器启动 ​

完整配置列表请参阅 API 参考。

在开发过程中，WXT 使用 Mozilla 的 web-ext 自动打开一个已安装扩展的浏览器窗口。

配置文件 ​

你可以在 3 个位置配置浏览器启动行为：

  1. <rootDir>/web-ext.config.ts：该文件被版本控制忽略，允许你为特定项目配置自己的选项，而不影响其他开发者

    ts
    import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  // ...
});

  2. <rootDir>/wxt.config.ts：通过 webExt 配置项，包含在版本控制中

  3. $HOME/web-ext.config.ts：为你计算机上的所有 WXT 项目提供默认值

使用示例 ​

设置浏览器可执行文件路径 ​

要设置或自定义开发时打开的浏览器：

ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  binaries: {
    chrome: '/path/to/chrome-beta', // 使用 Chrome Beta 代替常规 Chrome
    firefox: 'firefoxdeveloperedition', // 使用 Firefox Developer Edition 代替常规 Firefox
    edge: '/path/to/edge', // 运行 "wxt -b edge" 时打开 MS Edge
  },
});
ts
export default defineConfig({
  webExt: {
    binaries: {
      chrome: '/path/to/chrome-beta', // 使用 Chrome Beta 代替常规 Chrome
      firefox: 'firefoxdeveloperedition', // 使用 Firefox Developer Edition 代替常规 Firefox
      edge: '/path/to/edge', // 运行 "wxt -b edge" 时打开 MS Edge
    },
  },
});

默认情况下，WXT 会尝试自动检测 Chrome/Firefox 的安装位置。但是，如果你的 Chrome 安装在非标准位置，则需要如上所示手动设置。

持久化数据 ​

默认情况下，为了避免修改浏览器的现有配置文件，web-ext 每次运行 dev 脚本时都会创建一个全新的配置文件。

目前，只有基于 Chromium 的浏览器支持覆盖此行为，并在多次运行 dev 脚本时持久化数据。

要持久化数据，请在上述任一配置文件中设置 --user-data-dir 标志：

ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  chromiumArgs: ['--user-data-dir=./.wxt/chrome-data'],
});
ts
import { resolve } from 'node:path';
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  // 在 Windows 上，路径必须是绝对路径
  chromiumProfile: resolve('.wxt/chrome-data'),
  keepProfileChanges: true,
});

现在，下次运行 dev 脚本时，将在 .wxt/chrome-data/{profile-name} 中创建一个持久化配置文件。使用持久化配置文件，你可以安装开发工具扩展来辅助开发、让浏览器记住登录状态等，而无需担心下次运行 dev 脚本时配置文件被重置。

TIP

你可以为 --user-data-dir 使用任意目录，上面的示例为每个 WXT 项目创建了一个持久化配置文件。要为所有 WXT 项目创建一个共享配置文件，你可以将 chrome-data 目录放在用户主目录中。

禁用自动打开浏览器 ​

如果你更喜欢手动将扩展加载到浏览器中，可以禁用自动打开行为：

ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  disabled: true,
});

启用 Chrome 功能 ​

某些 API 在开发时默认被禁用，因为 web-ext 启动 Chrome 时使用了默认标志，例如 Prompt API。

如果你的扩展依赖于新功能或服务，可以通过 chromiumArgs 启用它们：

ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  chromiumArgs: [
    // 例如，此标志启用 Prompt API
    '--disable-features=DisableLoadExtensionCommandLineSwitch',
  ],
});

目前没有完整的列表说明哪些功能标志对应哪些 API 和服务。

或者，如果你找不到启用所需功能的标志，可以禁用开发时自动打开浏览器，然后使用你的常规 Chrome 配置文件进行开发。