MV2/MV3 双版本 Rspack 架构

[cyfung1031]

Good thinking — so you want a single codebase that compiles to both MV2 and MV3 bundles, where browser API differences (like chrome.action vs chrome.browserAction) are abstracted away.

The Core Idea

A compat layer that always exposes MV3-style APIs, but internally routes to MV2 APIs when built for MV2. Rspack injects the right implementation via a module alias at build time.

---

Project Structure

src/
  lib/
    browser/
      index.ts          ← always import from here in your code
      mv3.ts            ← passthrough (real MV3 APIs)
      mv2.ts            ← shims MV3 syntax → MV2 APIs
  background.ts
  manifest.json
rspack.config.ts
plugins/
  mv2-manifest.ts

---

The Compat Layer

src/lib/browser/mv3.ts — pure passthrough:

export const action = chrome.action;
export const scripting = chrome.scripting;
// add whatever else you use

src/lib/browser/mv2.ts — shims MV3 APIs to MV2:

// action → browserAction
export const action: typeof chrome.action = {
  ...chrome.browserAction,
  // MV3 has setBadgeTextColor, MV2 doesn't — polyfill or no-op
  setBadgeTextColor: chrome.browserAction.setBadgeTextColor ?? (() => {}),
  // openPopup doesn't exist in MV2
  openPopup: () => Promise.resolve(),
};

// scripting → executeScript shim
export const scripting: Partial<typeof chrome.scripting> = {
  executeScript: ({ target, files, func, args }) => {
    return new Promise((resolve, reject) => {
      const details: chrome.tabs.InjectDetails = {};
      if (files) details.file = files[0];
      if (func) details.code = `(${func})(${JSON.stringify(args ?? [])})`;
      chrome.tabs.executeScript(target.tabId!, details, (res) => {
        if (chrome.runtime.lastError) reject(chrome.runtime.lastError);
        else resolve(res as any);
      });
    });
  },
  insertCSS: ({ target, files, css }) => {
    return new Promise((resolve, reject) => {
      const details: chrome.tabs.InjectDetails = {};
      if (files) details.file = files[0];
      if (css) details.code = css;
      chrome.tabs.insertCSS(target.tabId!, details, () => {
        if (chrome.runtime.lastError) reject(chrome.runtime.lastError);
        else resolve();
      });
    });
  },
};

src/lib/browser/index.ts — this file is what you always import, and Rspack aliases it:

// This file is replaced wholesale by the alias.
// It exists only so TypeScript is happy.
export * from "./mv3";

---

Your App Code (one version forever)

// src/background.ts
import { action, scripting } from "./lib/browser";

chrome.tabs.onUpdated.addListener(async (tabId, info) => {
  if (info.status !== "complete") return;

  await action.setBadgeText({ text: "ON", tabId });
  await scripting.executeScript({
    target: { tabId },
    func: () => console.log("injected"),
  });
});

---

Rspack Config — Dual Build

// rspack.config.ts
import { Configuration } from "@rspack/core";
import path from "path";
import CopyPlugin from "copy-webpack-plugin";
import { MV2ManifestPlugin } from "./plugins/mv2-manifest";

const shared = (mv: 2 | 3): Configuration => ({
  entry: {
    background: "./src/background.ts",
    // popup, content, etc.
  },
  output: {
    path: path.resolve(__dirname, `dist/mv${mv}`),
    filename: "[name].js",
  },
  resolve: {
    alias: {
      // ← the key trick: swap the browser compat module per build
      "@src/lib/browser": path.resolve(
        __dirname,
        `src/lib/browser/mv${mv}.ts`
      ),
    },
    extensions: [".ts", ".js"],
  },
  module: {
    rules: [{ test: /\.ts$/, use: "builtin:swc-loader" }],
  },
  plugins: [
    new CopyPlugin({
      patterns: [{ from: "src/manifest.json", to: "manifest.json" }],
    }),
    ...(mv === 2 ? [new MV2ManifestPlugin()] : []),
  ],
});

export default [shared(2), shared(3)]; // Rspack runs both

Rspack supports exporting an array of configs — both builds run in parallel.

---

Define Constants Per Build (optional but useful)

Add to each config so you can conditionally compile code:

// in rspack config
new rspack.DefinePlugin({
  __MV__: JSON.stringify(mv), // 2 or 3
}),

Then in code:

if (__MV__ === 2) {
  // MV2-only workaround, tree-shaken out of MV3 build
}

Declare the global in a .d.ts:

declare const __MV__: 2 | 3;

---

Summary of the Pattern

Your code imports from "@src/lib/browser"
        ↓
  Rspack alias resolves it to:
  ┌──────────────┐     ┌──────────────┐
  │   mv3.ts     │  or │   mv2.ts     │
  │ (passthrough)│     │ (shims MV2)  │
  └──────────────┘     └──────────────┘
        ↓                     ↓
   dist/mv3/            dist/mv2/

The alias swap is the only build-time difference. Your source code stays 100% MV3-flavored.

---

简单来说，分开 mv2 mv3 folder 做
预设 export * from mv3
实际打包时，在 rspack 动手脚，把 mv3库换成 mv2库

只要两者的 function signature 一致就可以了

还可以用 __MV__ 做 tree-shaking

[CodFrm]

以后差距会越来越大，这种方案有点折磨了

[CodFrm]

我觉得可以直接砍掉那些不支持的功能，不过可能需要先整理一下，例如后台脚本/定时脚本，我觉得就不需要强求在firefox上运行了

[cyfung1031]

vscode connect 那个应该还好。改一下可以支持 （ Event Page 长期连结 VS Code）
不支持就只有 后台脚本/定时脚本 了。直接砍掉 就看你能不能接受吧

其他都正常可以在 Firefox MV3 跑

[CodFrm]

完全可以接受，不好实现的，非核心功能的，我都想砍掉（就比如你说的vscode connect，还要event page）

[cyfung1031]

后台脚本/定时脚本 呢？

[CodFrm]

可以不用，直接砍

或者在firefox上另外再出一个 scriptcat mv3 ，告知功能缺陷

现在的mv2的版本也还在，只是只处理bugfix了

[cyfung1031]

以前有人針對 Background User Script 提問過

https://groups.google.com/a/chromium.org/g/chromium-extensions/c/q9H8KwFLkMs

---

先開了一個 貼文 問一下 sandbox
不過估計是無望的

https://discourse.mozilla.org/t/firefox-mv3-any-plan-to-support-scripting-eval-in-sandbox/147853

[CodFrm]

说实话，firefox上没有太多用户，mv2使用起来也没什么大问题，不想花那么多精力去处理，而且处理后也是一个残缺的版本，不如就保持现状