> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 在浏览器扩展中使用 Vue.js

> 用 Vue 单文件组件搭建扩展 UI。Extension.js 会从依赖中检测 Vue，并配置 SFC 编译和别名。

Extension.js 会从依赖中检测 Vue，并自动配置单文件组件（SFC）的编译、框架别名以及开发期的更新行为。scoped 样式、Composition API 和 `<script setup>` 都无需额外的打包器接线即可使用。

## 什么场景适合用 Vue

* 你已经在生产环境中部署 Vue 应用。
* 你偏好使用 Vue 单文件组件，搭配 scoped 样式与 Composition API。
* 你希望扩展 UI 与既有的 Vue 架构保持一致。

## 模板示例

### `new-vue`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/new-vue/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=0f05d66951c6512c5fee920de0e097c1" alt="Template screenshot" width="2400" height="1800" data-path="images/examples/new-vue/screenshot.png" />

从第一天起就支持 SFC，搭建一个 Vue 新标签页体验。

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=new-vue
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=new-vue
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=new-vue
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=new-vue
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=new-vue
  ```
</CodeGroup>

仓库：[extension-js/examples/new-vue](https://github.com/extension-js/examples/tree/main/examples/new-vue)

### `content-vue`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/content-vue/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=828db99559e99c5ea991db16f7013769" alt="Template screenshot" width="2400" height="1800" data-path="images/examples/content-vue/screenshot.png" />

通过 content script 把 Vue 组件直接注入到网页里。

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=content-vue
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=content-vue
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=content-vue
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=content-vue
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=content-vue
  ```
</CodeGroup>

仓库：[extension-js/examples/content-vue](https://github.com/extension-js/examples/tree/main/examples/content-vue)

## 在现有扩展中使用

按下面的步骤把 Vue 添加到现有扩展。

### 安装

安装所需依赖：

<PackageManagerTabs command="install vue" />

如果想在现有项目中显式配置，再安装 Vue 的 SFC 工具链：

<PackageManagerTabs command="install -D vue-loader @vue/compiler-sfc" />

### 配置

Extension.js 期望 Vue 组件以 `.vue` 文件存在。它会在 Rspack 管线中配置 `vue-loader`、`VueLoaderPlugin` 以及 Vue 相关的 define 标志。

## 开发期行为

当 Extension.js 检测到 Vue 时，它会：

* 在框架插件中启用 `.vue` 编译。
* 应用 Vue 运行时别名（保持运行时解析一致）。
* 支持 content script 在相关 Vue SFC 变更后重新挂载的更新方式。

如果项目缺少可选的 Vue 工具，Extension.js 会安装并提示你重启。

### 排查

* **Vue 工具缺失警告：** 安装 `vue-loader` 与 `@vue/compiler-sfc`。
* **安装后提示重启：** 停止并重新运行 `extension dev`，让 Extension.js 加载新安装的 loader/plugin。
* **意外的 `.vue` 处理问题：** 确认 `vue` 出现在项目依赖中，以便 Extension.js 启用 Vue 集成。

## 用法示例

### 在新标签页扩展中

要在新标签页扩展中使用 Vue，把入口文件引入 HTML：

```html theme={null}
<!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>
```

```ts theme={null}
import { createApp } from "vue";
import App from "./App.vue";

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

```vue theme={null}
<!-- 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 应用挂载到注入的根节点上：

```ts theme={null}
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 保持精简。

## 下一步

* 进一步了解 [TypeScript 支持](/docs/languages-and-frameworks/typescript)。
* 探索 [Sass 和 Sass 模块](/docs/languages-and-frameworks/sass)。

## 视频讲解
