WXT中文文档（机翻）

Appearance

WXT 升级指南 ​

项目概述 ​

要升级 WXT 到最新版本...只需安装它即可！

bash
pnpm i wxt@latest

所有版本的 breaking changes ​

目前 WXT 还处于预发布状态。这意味着对 v0.X 的更改被视为 major 改变且带有 breaking changes。一旦 v1 发布，仅在 version bump 为 major 版本时才会有 breaking changes。

v0.18.5 到 v0.19.0 ​

vite-node 入口点加载器的变化 ​

默认的入口点加载器已更改为 vite-node。如果你使用任何依赖于 webextension-polyfill 的 NPM 包，你需要在 Vite 的 ssr.noExternal 选项中添加它们：

typescript
export default defineConfig({
  vite: () => ({ 
    ssr: { 
      noExternal: ['@webext-core/messaging', '@webext-core/proxy-service'], 
    }, 
  }), 
});

阅读完整的文档以获取更多详细信息。

这种变化启用：
  • 使用变量并在 entrypoint 选项中使用它们：
typescript
// entrypoints/content.ts
import { GOOGLE_MATCHES } from '~/utils/constants'

export default defineContentScript({
  matches: [GOOGLE_MATCHES],
  main: () => ...,
})
  • 使用 Vite 的特定 API，如 import.meta.glob 来定义 entrypoint 选项：
typescript
// entrypoints/content.ts
const providers: Record<string, any> = import.meta.glob('../providers/*', {
  eager: true,
});

export default defineContentScript({
  matches: Object.values(providers).flatMap(
    (provider) => provider.default.paths,
  ),
  async main() {
    console.log('Hello content.');
  },
});

基本上，你可以现在导入并执行 outside entrypoint 的操作 - 在之前的版本中是不能做的。但仍需谨慎。为了保持构建速度，建议避免在 main 函数外运行代码。

添加到 wxt.config.ts ​

如果要继续使用旧的方法，请在你的 wxt.config.ts 文件中添加以下内容：

typescript
export default defineConfig({
  entrypointLoader: 'jiti', 
});

WARNING

entrypointLoader: "jiti" 已被 deprecated 并将在下一个主要版本中删除。

v0.18.0 到 v0.18.5 ​

停用 CJS 支持 ​

WXT 不再随带 CommonJS 支持。如果你在使用 CJS，请按照以下步骤进行迁移：

  1. 在 package.json 中添加 "type": "module"。
  2. 将任何 .js 文件中使用 CJS 语法的文件名改为 .cjs，或使用 EMS 语法更新它们。

Vite 提供了对 EMS 的迁移步骤。请查看 https://vitejs.dev/guide/migration#deprecate-cjs-node-api 以获取更多细节。

v0.17.0 到 v0.18.0 ​

自动 MV3 host_permissions 到 MV2 permissions ​

出于谨慎，这个变化已标记为 breaking change，因为权限生成不同。

如果你在 wxt.config.ts 中的 manifest 中有 host_permissions 并且已经发布过扩展，请检查你的 permissions 和 host_permissions 是否与目标路径下的所有 .output/*/manifest.json 文件中的设置一致。权限变化可能导致扩展在更新时被禁用，并可能导致用户数量下降，因此请确保检查它们是否与之前的 manifest 版本一致。

v0.16.0 到 v0.17.0 ​

存储 - defineItem 要求 defaultValue 选项 ​

如果你使用 defineItem 并且没有默认值，则需要在选项和第一个类型参数中添加 defaultValue: null：

typescript
const item = storage.defineItem<number>("local:count", { 
const item = storage.defineItem<number | null>("local:count", { 
defaultValue: null, 
  version: ...,
  migrations: ...,
})

defaultValue 性质现在在传递第二个选项参数时是必需的。如果省略第二个选项参数，则它将默认为可选，就像之前一样。

typescript
const item: WxtStorageItem<number | null> =
  storage.defineItem<number>('local:count');
const value: number | null = await item.getValue();

存储 - 修改 watch 挑战 ​

如果不需要 TypeScript，则无需翻译此部分，这只是一个类型变化。

typescript
const item = storage.defineItem<number>('local:count', { defaultValue: 0 });
item.watch((newValue: number | null, oldValue: number | null) => { 
item.watch((newValue: number, oldValue: number) => { 
  // ...
});

v0.15.0 到 v0.16.0 ​

输出目录结构更改 ​

JS 入口点在输出目录中的位置已更改。除非你有某种特定的后处理工作需要引用文件，否则无需进行任何修改。

.output/
  <target>/
    chunks/
      some-shared-chunk-<hash>.js
      popup-<hash>.js
    popup.html
    popup.html
    popup.js

v.14 到 v0.15 ​

重命名 zip.ignoredSources 到 zip.excludeSources ​

typescript
// wxt.config.ts
export default defineConfig({
  zip: {
    ignoredSources: [
      /*...*/
    ], 
    excludeSources: [
      /*...*/
    ], 
  },
});

重命名未文档化的常量 ​

现在在 https://wxt.dev/guide/multiple-browsers.html#runtime 中进行了文档更新。以下是重命名的常量：

  • __BROWSER__ → import.meta.env.BROWSER
  • __COMMAND__ → import.meta.env.COMMAND
  • __MANIFEST_VERSION__ → import.meta.env.MANIFEST_VERSION
  • __IS_CHROME__ → import.meta.env.CHROME
  • __IS_FIREFOX__ → import.meta.env.FIREFOX
  • __IS_SAFARI__ → import.meta.env.SAFARI
  • __IS_EDGE__ → import.meta.env.EDGE
  • __IS_OPERA__ → import.meta.env.OPERA

v0.13 到 v0.14 ​

内容脚本 UI API 变更 ​

createContentScriptUi 和 createContentScriptIframe 以及它们的一些选项已更改：

  • createContentScriptUi({ ... }) → createShadowRootUi({ ... })
  • createContentScriptIframe({ ... }) → createIframeUi({ ... })
  • type: "inline" | "overlay" | "modal" 已更改为 position: "inline" | "overlay" | "modal"
  • onRemove 现在在移除 UI 之前调用，此前是在移除后调用
  • mount 选项已更改为 onMount，以更好地匹配相关选项 onRemove

v0.12 到 v0.13 ​

新的 wxt/storage API ​

wxt/storage 不再依赖于 unstorage。unstorage 中的一些 API，如 prefixStorage，已移除，而其他一些，如 snapshot，现在是 storage 对象的方法。大多数标准用法仍然有效。请参阅 https://wxt.dev/guide/storage 和 https://wxt.dev/api/reference/wxt/storage/ (#300)。

v0.11 到 v0.12 ​

导出 API 更改 ​

defineContentScript 和 defineBackground 现在从 wxt/sandbox 转移到 wxt/client。(#284)

  • 如果你使用自动导入，无需更改
  • 如果你禁用了自动导入，请手动更新你的导入声明：
    ts
    import { defineBackground, defineContentScript } from 'wxt/client'; 
import { defineBackground, defineContentScript } from 'wxt/sandbox';

v0.10 到 v0.11 ​

Vite 5 ​

你需要更新任何其他 Vite 插件以支持 Vite 5。

v0.9 到 v0.10 ​

延伸 icon 识别 ​

WXT 不再发现除 .png 外的图片格式。如果你之前使用过 .jpg, .jpeg, .bmp 或 .svg，你需要将它们转换为 .png 文件或手动添加到 wxt.config.ts 中。

v0.8 到 v0.9 ​

去除 WebWorker 类型 ​

从 .wxt/tsconfig.json 移除了 ["WebWorker"] 类型。这些类型在 MV3 项目中使用服务 worker 时有用。

要将它们添加回项目，请在项目的 TSConfig 中添加以下内容：

json
{
  "extends": "./.wxt/tsconfig.json",
  "compilerOptions": {

    "lib": ["ESNext", "DOM", "WebWorker"] 
  } 
}

v0.7 到 v0.8 ​

新增 defineUnlistedScript 方法 ​

未列出的脚本必须现在 export default defineUnlistedScript(...)。

命名类型更改 ​

将 BackgroundScriptDefintion 命名为 BackgroundDefinition。

v0.6 到 v0.7 ​

内容脚本 CSS 路径更改 ​

内容脚本 CSS 的输出路径已更改。从前是 assets/<name>.css，现在改为 content-scripts/<name>.css，以匹配文档。

v0.5 到 v0.6 ​

必须指定 vite 配置选项为函数 ​

如果你之前使用过对象形式，则需要将 vite 配置更改为函数。例如：

从前：

typescript
vite: { ... }

现在应改为：

typescript
vite: () => ({ ... })

v0.4 到 v0.5 ​

移动公共目录 ​

默认的 publicDir 已从 <rootDir>/public 更改为 <srcDir>/public。

v0.3 到 v0.4 ​

默认路径前缀更改 ​

在 .wxt/tsconfig.json 中使用相对路径前缀。

v0.2 到 v0.3 ​

移动公共目录 ​

默认的 publicDir 已从 <srcDir>/public 更改为 <rootDir>/public。

类型安全性增强 ​

添加类型安全到 browser.runtime.getURL。

v0.1 到 v0.2 ​

命名更改 ​

重命名 defineBackgroundScript 为 defineBackground。