> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# Vue 插件


[源码](https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-vue)

Vue 插件提供了对 Vue 3 SFC（单文件组件）的支持，插件内部集成了 [rspack-vue-loader](https://npmjs.com/package/rspack-vue-loader)。

:::tip
对于 Vue 3 JSX / TSX 语法，请使用 [Vue JSX 插件](https://github.com/rstackjs/rsbuild-plugin-vue-jsx)。
:::

## 快速开始

### 安装插件

执行以下命令安装插件：


```sh [npm]
npm add @rsbuild/plugin-vue -D
```

```sh [yarn]
yarn add @rsbuild/plugin-vue -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-vue -D
```

```sh [bun]
bun add @rsbuild/plugin-vue -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-vue -D
```

### 注册插件

在 Rsbuild 配置中注册插件：

```ts title="rsbuild.config.ts"
import { pluginVue } from '@rsbuild/plugin-vue';

export default {
  plugins: [pluginVue()],
};
```

注册后，即可在代码中引入 `*.vue` 单文件组件。

## 选项

如果你需要自定义 Vue 的编译行为，可以使用以下配置项。

### vueLoaderOptions

传递给 `rspack-vue-loader` 的选项，请查阅 [Vue Loader 文档](https://vue-loader.vuejs.org/) 来了解具体用法。

- **类型：** `VueLoaderOptions`
- **默认值：**

```js
const emitCss = config.output.emitCss ?? config.output.target === 'web';
const defaultOptions = {
  compilerOptions: {
    preserveWhitespace: false,
  },
  experimentalInlineMatchResource: emitCss,
};
```

- **示例：**

```ts
pluginVue({
  vueLoaderOptions: {
    hotReload: false,
  },
});
```

### splitChunks

当使用 Rsbuild 的 [默认拆包 preset](/zh/config/split-chunks.md#default) 时，该插件会将与 `vue` 和 `vue-router` 相关的包拆分到独立的 chunk 中。

- `lib-vue.js`：包含 `vue`、`rspack-vue-loader`，以及它们的子依赖（`@vue/shared`，`@vue/reactivity`，`@vue/runtime-dom`，`@vue/runtime-core`）。
- `lib-router.js`：包含 `vue-router`。

该选项用于控制这一行为，决定是否需要将 `vue` 和 `router` 相关的包拆分为单独的 chunk。

- **类型：**

```ts
type SplitVueChunkOptions = {
  vue?: boolean;
  router?: boolean;
};
```

- **默认值：**

```ts
const defaultOptions = {
  vue: true,
  router: true,
};
```

- **示例：**

```ts
pluginVue({
  splitChunks: {
    vue: false,
    router: false,
  },
});
```

### test

用于自定义 Vue 单文件组件（SFC）的匹配规则。

- **类型：** [Rspack.RuleSetCondition](https://rspack.rs/zh/config/module-rules#condition)
- **默认值：** `/\.vue$/`
- **版本：** `>= 1.2.1`

通过该选项，你可以扩展 Vue 插件对其他文件类型的处理能力。例如，先使用某个插件或 loader 将 `.md` 文件转换为 Vue 组件，然后可以在 Vue 插件中通过 `test` 选项同时匹配 `.vue` 和 `.md` 文件：

```ts
pluginVue({
  test: /\.(vue|md)$/,
});
```

## 常见问题

### /deep/ 选择器导致编译报错

`/deep/` 是从 Vue v2.7 开始废弃的用法，它不是一个合法的 CSS 语法，因此在编译时，Lightning CSS 等 CSS 编译工具会抛出错误。

你可以使用 `:deep()` 代替它，更多用法参考 [Vue - Deep Selectors](https://vuejs.org/api/sfc-css-features.html#deep-selectors)。

```html
<style scoped>
  .a :deep(.b) {
    /* ... */
  }
</style>
```

> 你也可以参考 [Vue - RFC 0023](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0023-scoped-styles-changes.md) 了解更多。