在瀏覽器擴充功能中使用 Vue.js

Extension.js 會從相依套件偵測 Vue，並自動設定單一檔案元件（SFC）編譯、框架別名與開發階段的更新行為。scoped 樣式、Composition API 與 <script setup> 都不需要額外的 bundler 串接設定。

什麼情況下適合使用 Vue

你已經有正式上線的 Vue 應用程式。
你偏好以 Vue SFC 撰寫，並搭配 scoped 樣式與 Composition API。
你希望擴充功能的 UI 介面能反映既有的 Vue 架構。

範本範例

`new-vue`

從第一天就具備 SFC 支援，打造 Vue new-tab 體驗。

npx extension@latest create my-extension --template=newtab-vue

pnpx extension@latest create my-extension --template=newtab-vue

yarn dlx extension@latest create my-extension --template=newtab-vue

bunx extension@latest create my-extension --template=newtab-vue

deno run -A npm:extension@latest create my-extension --template=newtab-vue

Repository: extension-js/examples/newtab-vue

`content-vue`

以 content script 設定，將 Vue 元件直接注入網頁。

npx extension@latest create my-extension --template=content-vue

pnpx extension@latest create my-extension --template=content-vue

yarn dlx extension@latest create my-extension --template=content-vue

bunx extension@latest create my-extension --template=content-vue

deno run -A npm:extension@latest create my-extension --template=content-vue

Repository: extension-js/examples/content-vue

在既有擴充功能中使用

依下列步驟把 Vue 加入既有擴充功能。

安裝

安裝所需相依套件：

npm install vue

pnpm add vue

yarn add vue

bun add vue

deno add npm:vue

如果要在既有專案中明確設定，也安裝 Vue 的 SFC 工具鏈：

npm install -D vue-loader @vue/compiler-sfc

pnpm add -D vue-loader @vue/compiler-sfc

yarn add -D vue-loader @vue/compiler-sfc

bun add -d vue-loader @vue/compiler-sfc

deno add -D npm:vue-loader npm:@vue/compiler-sfc

當缺少 vue-loader 或 @vue/compiler-sfc 這類選用的 Vue 整合套件時，建置錯誤會指出與內建工具鏈相符的確切版本。錯誤中的安裝指令會依你專案使用的套件管理器來呈現。

設定

Extension.js 會期望 Vue 元件位於 .vue 檔案。它會在 Rspack pipeline 中設定 vue-loader、VueLoaderPlugin 與 Vue 相關的 define flag。Vue 專案中的 JSX 與 TSX 頁面會透過 vue/jsx-runtime 編譯。

開發行為

當 Extension.js 偵測到 Vue 時，會：

在框架 plugin 中啟用 .vue 編譯。
套用 Vue 執行期別名（讓 runtime 解析保持一致）。
在 Vue SFC 變動時，透過重新掛載支援 content script 的更新。

若專案缺少選用的 Vue 工具，Extension.js 會提出確切的安裝指令並發出警告，而不會替你安裝。

疑難排解

缺少 Vue 工具的警告： 安裝 vue-loader 與 @vue/compiler-sfc。
安裝後要求重新啟動： 停止並重新執行 extension dev，讓 Extension.js 可以載入剛安裝的 loader/plugin。
.vue 處理出現非預期問題： 請確認 vue 已出現在專案相依套件中，讓 Extension.js 能偵測 Vue 整合。

使用範例

在 new tab 擴充功能中

要在 new tab 擴充功能中使用 Vue，請在 HTML 中包含你的入口檔：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>New Extension</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this extension.</noscript>
    <div id="app"></div>
  </body>
  <script src="./main.ts"></script>
</html>

import { createApp } from "vue";
import App from "./App.vue";

createApp(App).mount("#app");

<!-- App.vue -->
<template>
  <h1>Hello, Vue.js Extension!</h1>
</template>

<script setup lang="ts">
// Component logic goes here.
</script>

<style scoped>
h1 {
  color: #42b983;
}
</style>

在 `content_script` 檔中

對於 content script，將 Vue app 掛載到注入的根節點：

import { createApp } from "vue";
import App from "./App.vue";
import "./content.css";

const rootDiv = document.createElement("div");
rootDiv.id = "extension-root";
document.body.appendChild(rootDiv);

createApp(App).mount("#extension-root");

最佳實務

讓 UI 入口維持以框架為主（main.ts、App.vue），並把擴充功能 API 放在專屬模組。
在 SFC 中盡量使用 scoped 樣式，降低擴充功能頁面的樣式外洩。
對於較大的 UI，將元件與共用 composable 拆分，讓 content script 保持精簡。

執行階段建置與 Options API

從 4.1.19 開始，Vue 專案打包的是僅含執行階段的建置 vue.runtime.esm-bundler.js，也就是 vue 套件在 module 進入點指定的檔案。Extension.js 會把 vue$、@vue/runtime-dom、@vue/runtime-core 與 @vue/shared 都別名到那個建置，這樣你的應用程式與任何被轉譯的 workspace 相依套件共用同一個 Vue 實例。完整建置帶有範本編譯器，擴充功能的 CSP 無法執行它，而且它的 innerHTML 與 Function 呼叫會通不過 addons.mozilla.org 的商店檢查。執行階段建置沒有範本編譯器，所以範本必須預先編譯。單檔元件正好提供這一點：vue-loader 在建置時編譯每一個 <template>。DOM 內範本與字串形式的 template: 選項不受支援。Vue 會在主控台發出警告，並且對這樣的元件不渲染任何內容。要保留執行階段編譯，請在 extension.config.js 中把 vue$ 別名到完整建置：

extension.config.js

export default {
  config: (config) => {
    config.resolve = config.resolve || {};
    config.resolve.alias = {
      ...(config.resolve.alias || {}),
      vue$: "vue/dist/vue.esm-bundler.js",
    };
    return config;
  },
};

那個建置用 new Function 編譯範本，這需要擴充功能 CSP 裡有 unsafe-eval。Manifest V3 的擴充功能頁面禁止它，所以這個別名只對 Manifest V2 專案有幫助。 Options API 在正式環境保持開啟。Extension.js 在每種模式下都把 __VUE_OPTIONS_API__ 設為 true，所以用 data()、methods 或 computed 寫的元件在出貨的 bundle 裡照常運作。__VUE_PROD_DEVTOOLS__ 與 hydration 不一致的詳情在正式環境是關閉的。還有一條 define 適用於每一個 bundle、每一種框架。自由識別字 global 被定義為 globalThis，Rspack 自己的 global 輔助程式碼被關閉。那段輔助程式碼會退回到 Function("return this")，通不過 addons.mozilla.org 的商店檢查，所以你的 bundle 裡不會出現這樣的 shim。

下一步

進一步了解 TypeScript 支援。
探索 Sass 與 Sass modules。

Introduction

Browser extension fundamentals

Getting started

範本

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

在瀏覽器擴充功能中使用 Vue.js

什麼情況下適合使用 Vue

範本範例

`new-vue`

`content-vue`

在既有擴充功能中使用

安裝

設定

開發行為

疑難排解

使用範例

在 new tab 擴充功能中

在 `content_script` 檔中

最佳實務

執行階段建置與 Options API

下一步

影片導覽

模板示範

​什麼情況下適合使用 Vue

​範本範例

​new-vue

​content-vue

​在既有擴充功能中使用

​安裝

​設定

​開發行為

​疑難排解

​使用範例

​在 new tab 擴充功能中

​在 content_script 檔中

​最佳實務

​執行階段建置與 Options API

​下一步

​影片導覽

​模板示範

什麼情況下適合使用 Vue

範本範例

`new-vue`

`content-vue`

在既有擴充功能中使用

安裝

設定

開發行為

疑難排解

使用範例

在 new tab 擴充功能中

在 `content_script` 檔中

最佳實務

執行階段建置與 Options API

下一步

影片導覽

模板示範