WXT 中文文档

Appearance

迁移到 WXT ​

如果你在迁移到 WXT 的过程中遇到问题，欢迎在 GitHub 上发起讨论或在 Discord 中寻求帮助！

概述 ​

首先生成一个新的原始项目，然后逐个文件地合并到你的项目中。

sh
cd path/to/your/project
pnpm dlx wxt@latest init example-wxt --template vanilla

TIP

建议在开始之前先阅读项目结构。 你可以在 wxt.config.ts 中自定义目录名称以匹配你的项目需求。

一般来说，你需要：

  安装 wxt
  在项目的 tsconfig.json 中继承 .wxt/tsconfig.json
  更新/创建 package.json 脚本以使用 wxt（不要忘记 postinstall）
  将入口文件移动到 entrypoints/ 目录
  将资源文件移动到 assets/ 或 public/ 目录
  将 manifest.json 内容移动到 wxt.config.ts 中
  将自定义导入语法转换为与 Vite 兼容的方式
  为 JS 入口文件添加默认导出（defineBackground、defineContentScript 或 defineUnlistedScript）
  使用 browser 全局变量替代 chrome
  ⚠️ 对比最终的 manifest.json 文件，确保权限和主机权限没有变化

WARNING

如果你的扩展已经在 Chrome Web Store 上线，请使用 Google 的更新测试工具来确保没有请求新的权限。

每个项目都不一样，因此没有一种万能的迁移方案。只需确保 wxt dev 能正常运行、wxt build 能生成可用的扩展，并且 manifest.json 中的权限列表没有变化。如果一切正常，你的扩展就迁移完成了！

常用工具/框架 ​

以下是针对其他常用框架/构建工具的具体迁移步骤。

Plasmo ​

  1. 安装 wxt
  2. 将入口文件移动到 entrypoints/ 目录
    • 对于 JS 入口文件，将用于配置的命名导出合并到 WXT 的默认导出中
    • 对于 HTML 入口文件，你不能直接使用 JSX/Vue/Svelte 文件，需要创建一个 HTML 文件并手动创建和挂载你的应用。请参考 React、Vue 和 Svelte 模板作为示例。
  3. 将公共 assets/* 移动到 public/ 目录
  4. 如果使用了 CSUI，请迁移到 WXT 的 createContentScriptUi
  5. 将 Plasmo 的自定义导入解析转换为 Vite 的方式
  6. 如果通过 URL 导入远程代码，请添加 url: 前缀以兼容 WXT
  7. 将你的 Plasmo 标签（--tag）替换为 WXT 构建模式（--mode）
  8. ⚠️ 对比旧的生产环境 manifest 和 .output/*/manifest.json。它们应该与之前的内容相同。如果不同，请调整你的入口文件和配置直到一致。

CRXJS ​

如果你使用了 CRXJS 的 Vite 插件，迁移过程非常简单！CRXJS 和 WXT 的主要区别在于工具如何决定构建哪些入口文件。CRXJS 查看你的 manifest（以及 Vite 配置中的"未列出"条目），而 WXT 查看 entrypoints 目录中的文件。

迁移步骤：

  1. 将所有入口文件移动到 entrypoints 目录，并重构为 WXT 的风格（TS 文件需要有默认导出）。
  2. 将入口文件特定选项从 manifest 中移出，放入入口文件本身（如 content script 的 matches 或 run_at）。
  3. 将其他 manifest.json 选项移入 wxt.config.ts 文件，如权限等。
  4. 为简化操作，你可能需要先禁用自动导入（除非你已经通过 unimport 或 unplugin-auto-imports 在使用它们）。如果你喜欢这个功能，可以在完成迁移后再启用。
  5. 更新你的 package.json，包含所有 WXT 建议的脚本（见步骤 4）
  6. 特别注意，确保在 package.json 中添加 "postinstall": "wxt prepare" 脚本。
  7. 删除你的 vite.config.ts 文件。将所有插件移到 wxt.config.ts 文件中。如果你使用前端框架，请安装相应的 WXT 模块。
  8. 更新你的 TypeScript 项目。继承 WXT 生成的配置，并在 wxt.config.ts 文件中添加路径别名。
  9. ⚠️ 对比旧的生产环境 manifest 和 .output/*/manifest.json。它们应该与之前的内容相同。如果不同，请调整你的入口文件和配置直到一致。

这里有一个迁移示例：GitHub Better Line Counts - CRXJS → WXT

vite-plugin-web-extension ​

由于你已经在使用 Vite，迁移过程非常简单。

  1. 安装 wxt
  2. 移动并重构你的入口文件为 WXT 的风格（带有默认导出）
  3. 更新 package.json 脚本以使用 wxt
  4. 添加 "postinstall": "wxt prepare" 脚本
  5. 将 manifest.json 移入 wxt.config.ts
  6. 将 vite.config.ts 中的自定义设置移入 wxt.config.ts
  7. ⚠️ 对比旧的生产环境 manifest 和 .output/*/manifest.json。它们应该与之前的内容相同。如果不同，请调整你的入口文件和配置直到一致。