从 WXT 迁移到 Extension.js

​

哪些会变，哪些不变

• 文件约定式入口（entrypoints/popup/、entrypoints/content.ts）变成真实 manifest.json 中显式的入口。
• wxt.config.ts 中的 manifest 选项（以及 HTML 入口里的 <meta name="manifest.*"> 标签）移入 manifest.json。
• defineBackground() ／ defineContentScript() 包装拆开成普通模块。
• WXT 的自动导入变成显式导入。
• wxt / wxt build / wxt zip 变成 extension dev / extension build --zip。
• import.meta.env.WXT_* 环境变量变成 EXTENSION_PUBLIC_*。

​

第 1 步：安装 Extension.js

npm install extension@latest --save-dev
npm uninstall wxt

​

第 2 步：编写 manifest

​

第 3 步：拆开 defineBackground 与 defineContentScript

export default defineContentScript({
  matches: ["https://example.com/*"],
  main(ctx) {
    console.log("content script running");
  },
});

{
  "content_scripts": [
    {
      "matches": ["https://example.com/*"],
      "js": ["content/script.ts"]
    }
  ]
}

console.log("content script running");

• ctx（ContentScriptContext）： WXT 的 ctx 会在扩展更新、content script 被孤立时取消正在进行的工作。请把绑定在 ctx 上的监听器换成常规的 addEventListener 调用。如果你确实依赖失效处理，可以用 chrome.runtime.id 检查来保护长期存活的回调。
• createShadowRootUi ／ createIntegratedUi： 改用常规 DOM 代码挂载你的组件：创建一个容器元素，把它附加到页面上，再渲染进去。完整模式（包含使用 shadow DOM 隔离样式）参见 Content scripts。

​

第 4 步：把自动导入改成显式导入

• browser.* 调用：保持不变。extension dev 默认应用 polyfill，extension build 需要 --polyfill。改用 chrome.* 同样可行。
• WXT 的 storage：import { storage } from "@wxt-dev/storage" 作为独立包继续可用。
• 框架相关的自动导入（来自 @wxt-dev/module-react 等）：直接从框架包本身导入。

​

第 5 步：环境变量与脚本

• 把 .env 文件中的 WXT_*（以及 VITE_*）变量重命名为 EXTENSION_PUBLIC_*，并把 import.meta.env.WXT_FOO 换成 process.env.EXTENSION_PUBLIC_FOO。参见 环境变量。
• 更新 package.json 脚本：

{
  "scripts": {
    "dev": "extension dev",
    "build": "extension build",
    "start": "extension start"
  }
}

extension build --browser=chrome,firefox --zip

​

第 6 步：验证

extension dev --browser=chrome

​

常见坑

• Manifest V2： WXT 支持把 MV2 作为构建目标，而 Extension.js 面向 Manifest V3。如果你仍在发布 MV2 构建，请先完成那次迁移。参见 Manifest V3 概念。
• public/ 目录： WXT 的 public/ 中的文件会原样复制。Extension.js 对 public/ 也是同样处理，从 manifest 或 HTML 引用的路径继续有效。
• assets/ 与 ~／@ 别名： 请在 tsconfig.json 的 paths 中映射这些别名，或者改用相对导入。参见 路径解析。
• WXT 模块（@wxt-dev/module-react、-vue、-svelte）：不再需要，因为框架支持是内置的。可以对照一个全新的 模板 来查看参考配置。
• app.config.ts 运行时配置： 换成你自己的模块（一个普通的导出对象就能提供同样的能力，且不用多一层框架）。

​

另请参阅

• Extension.js vs WXT
• 从 Plasmo 迁移
• 从 CRXJS 迁移
• 跨浏览器兼容性
• 重载与 HMR