WXT

简体中文

English

简体中文

English

Appearance

迁移到 WXT ​

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

概览 ​

始终建议先生成一个新的 vanilla 项目，然后将其内容逐个文件合并到你的项目中。

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

通常，你需要：

  安装 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 文件，确保权限和 host 权限未发生变化

WARNING

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

每个项目都不同，因此没有一套通用的迁移方案。只需确保 wxt dev 能运行，wxt build 能生成可用的扩展，并且 manifest.json 中的权限列表没有变化。如果这些都没问题，你就完成了迁移！

常用工具/框架 ​

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

Plasmo ​

  1. 安装 wxt
  2. 将入口文件移入 entrypoints/ 目录
    • 对于 JS 入口文件，将用于配置 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. 用 WXT 构建模式（--mode）替换你的 Plasmo 标签（--tag）
  8. ⚠️ 对比旧的生产 manifest 与 .output/*/manifest.json，内容应保持一致。如有不同，调整入口文件和配置直到一致。

CRXJS ​

如果你使用了 CRXJS 的 vite 插件，只需简单重构！CRXJS 和 WXT 的主要区别在于如何决定构建哪些入口。CRXJS 通过 manifest（以及 vite 配置中的“unlisted”入口）决定，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. 特别注意添加 "postinstall": "wxt prepare" 脚本到 package.json。
  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，内容应保持一致。如有不同，调整入口文件和配置直到一致。