> 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 CLI

本章节介绍如何将 [Vue CLI](https://github.com/vuejs/vue-cli) 项目迁移到 Rsbuild。

## 安装依赖

首先，将 Vue CLI 的 npm 依赖替换为 Rsbuild 的依赖。

- 移除 Vue CLI 的依赖：


```sh [npm]
npm remove @vue/cli-service @vue/cli-plugin-babel @vue/cli-plugin-eslint
```

```sh [yarn]
yarn remove @vue/cli-service @vue/cli-plugin-babel @vue/cli-plugin-eslint
```

```sh [pnpm]
pnpm remove @vue/cli-service @vue/cli-plugin-babel @vue/cli-plugin-eslint
```

```sh [bun]
bun remove @vue/cli-service @vue/cli-plugin-babel @vue/cli-plugin-eslint
```

```sh [deno]
deno remove npm:@vue/cli-service npm:@vue/cli-plugin-babel npm:@vue/cli-plugin-eslint
```

- 安装 Rsbuild 的依赖：


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

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

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

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

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

:::tip
如果你的项目是基于 Vue 2 的，请将 `@rsbuild/plugin-vue` 替换为 `@rsbuild/plugin-vue2`。
:::

## 更新 npm scripts

下一步，将 package.json 中的 npm scripts 更新为 Rsbuild 的 CLI 命令。

```json title="package.json"
{
  "scripts": {
    "serve": "vue-cli-service serve", // [!code --]
    "build": "vue-cli-service build", // [!code --]
    "serve": "rsbuild", // [!code ++]
    "build": "rsbuild build", // [!code ++]
    "preview": "rsbuild preview" // [!code ++]
  }
}
```

:::tip
Rsbuild 未集成 ESLint，因此没有提供用于替换 `vue-cli-service lint` 的命令，可直接使用 ESLint 的 [CLI 命令](https://eslint.org/docs/latest/use/command-line-interface) 作为替代。
:::

## 创建配置文件

在 package.json 的同级目录下创建 Rsbuild 的配置文件 `rsbuild.config.ts`，并添加以下内容：

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

export default defineConfig({
  plugins: [pluginVue()],
  source: {
    // 指定入口文件
    entry: {
      index: './src/main.js',
    },
  },
});
```

:::tip
如果你的项目是基于 Vue 2 的，请使用 `import { pluginVue2 } from '@rsbuild/plugin-vue2';`。
:::

## HTML 模板

Vue CLI 默认使用 `public/index.html` 文件作为 HTML 模板。在 Rsbuild 中，通过 [html.template](/zh/config/html/template.md) 指定 HTML 模板：

```ts title="rsbuild.config.ts"
export default defineConfig({
  html: {
    template: './public/index.html',
  },
});
```

在 HTML 模板中，如果使用了 Vue CLI 的 `BASE_URL` 变量，请替换为 Rsbuild 的 [assetPrefix 变量](/zh/config/html/template-parameters.md)，并使用斜杠进行连接：

```html
<link rel="icon" href="<%= BASE_URL %>favicon.ico" />
<!-- [!code --] -->
<link rel="icon" href="<%= assetPrefix %>/favicon.ico" />
<!-- [!code ++] -->
```

至此，已完成从 Vue CLI 到 Rsbuild 的基本迁移。运行 `npm run serve` 启动开发服务器。

## 配置迁移

以下是 Vue CLI 配置对应的 Rsbuild 配置：

| Vue CLI                                                                                                                                 | Rsbuild                                                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [publicPath](https://cli.vuejs.org/config/#publicpath)                                                                                  | [dev.assetPrefix](/zh/config/dev/asset-prefix.md) / [output.assetPrefix](/zh/config/output/asset-prefix.md)                                                                    |
| [outputDir](https://cli.vuejs.org/config/#outputdir) / [assetsDir](https://cli.vuejs.org/config/#assetsdir)                             | [output.distPath](/zh/config/output/dist-path.md)                                                                                                                              |
| [filenameHashing](https://cli.vuejs.org/config/#filenamehashing)                                                                        | [output.filenameHash](/zh/config/output/filename-hash.md)                                                                                                                      |
| [pages](https://cli.vuejs.org/config/#pages)                                                                                            | [source.entry](/zh/config/source/entry.md) / [html.template](/zh/config/html/template.md) / [html.title](/zh/config/html/title.md)                                             |
| [transpileDependencies](https://cli.vuejs.org/config/#transpiledependencies)                                                            | [source.include](/zh/config/source/include.md)                                                                                                                                 |
| [productionSourceMap](https://cli.vuejs.org/config/#productionsourcemap) / [css.sourceMap](https://cli.vuejs.org/config/#css-sourcemap) | [output.sourceMap](/zh/config/output/source-map.md)                                                                                                                            |
| [crossorigin](https://cli.vuejs.org/config/#crossorigin)                                                                                | [html.crossorigin](/zh/config/html/crossorigin.md)                                                                                                                             |
| [configureWebpack](https://cli.vuejs.org/config/#configurewebpack)                                                                      | [tools.rspack](/zh/config/tools/rspack.md)                                                                                                                                     |
| [chainWebpack](https://cli.vuejs.org/config/#chainwebpack)                                                                              | [tools.bundlerChain](/zh/config/tools/bundler-chain.md)                                                                                                                        |
| [css.extract](https://cli.vuejs.org/config/#css-extract)                                                                                | [output.injectStyles](/zh/config/output/inject-styles.md)                                                                                                                      |
| [css.loaderOptions](https://cli.vuejs.org/config/#css-loaderoptions)                                                                    | [tools.cssLoader](/zh/config/tools/css-loader.md) / [less](/zh/plugins/list/plugin-less.md) / [sass](/zh/plugins/list/plugin-sass.md) / [postcss](/zh/config/tools/postcss.md) |
| [devServer.proxy](https://cli.vuejs.org/config/#devserver-proxy)                                                                        | [server.proxy](/zh/config/server/proxy.md)                                                                                                                                     |

说明：

- 在迁移 configureWebpack 时，注意大部分 webpack 和 Rspack 配置是相同的，但也存在一些差异或 Rspack 未实现的功能。
- 上述表格尚未覆盖到 Vue CLI 的所有配置，欢迎补充。

## 环境变量

Vue CLI 默认会将 `VUE_APP_` 开头的环境变量注入到 client 代码中，而 Rsbuild 默认会注入 `PUBLIC_` 开头的环境变量（参考 [public 变量](/zh/guide/advanced/env-vars.md#public-variables)）。

为了兼容 Vue CLI 的行为，可手动调用 Rsbuild 提供的 [loadEnv](/zh/api/javascript-api/core.md#loadenv) 方法来读取 `VUE_APP_` 开头的环境变量，并通过 [source.define](/zh/config/source/define.md) 配置项注入到 client 代码中。

```ts title="rsbuild.config.ts"
import { defineConfig, loadEnv } from '@rsbuild/core';

const { publicVars } = loadEnv({ prefixes: ['VUE_APP_'] });

export default defineConfig({
  source: {
    define: publicVars,
  },
});
```

## 内容补充

当前文档只涵盖了迁移过程的部分事项，如果你发现有合适的内容可以补充，欢迎通过 pull request 来完善文档 🤝。

> Rsbuild 的文档位于 [rsbuild/website](https://github.com/web-infra-dev/rsbuild/tree/main/website) 目录。