#Vite

本章节介绍如何将 Vite 项目迁移到 Rsbuild。

#安装依赖

首先你需要把 Vite 相关的 npm 依赖替换为 Rsbuild 的依赖。

• 移除 Vite 的依赖：

npm remove vite

yarn remove vite

pnpm remove vite

bun remove vite

deno remove npm:vite

• 安装 Rsbuild 的依赖：

npm add @rsbuild/core -D

yarn add @rsbuild/core -D

pnpm add @rsbuild/core -D

bun add @rsbuild/core -D

deno add npm:@rsbuild/core -D

#更新 npm scripts

下一步，你需要把 package.json 中的 npm scripts 更新为 Rsbuild 的 CLI 命令。

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "dev": "rsbuild",
    "build": "rsbuild build",
    "preview": "rsbuild preview"
  }
}

#创建配置文件

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

import { defineConfig } from '@rsbuild/core';

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

#构建入口

Rsbuild 与 Vite 默认的构建入口不同，Vite 使用 index.html 作为默认入口，而 Rsbuild 会自动检测 src/index.* 模块，例如 src/index.ts 或 src/index.js。

从 Vite 迁移到 Rsbuild 时，你可以使用 Rsbuild 提供的 source.entry 来设置构建入口，html.template 来设置模板。

以一个新建的 Vite 项目为例，首先删除 index.html 中的 <script> 标签：

<script type="module" src="/src/main.ts"></script>

然后添加如下配置即可。

export default {
  html: {
    template: './index.html',
  },
  source: {
    entry: {
      index: './src/main.ts',
    },
  },
};

Rsbuild 会在构建时自动注入 <script> 标签到生成的 HTML 文件中。

#迁移插件

大部分常见的 Vite 插件可以轻松地迁移到 Rsbuild 插件，比如：

参考 插件列表 来了解更多可用的插件。

#配置迁移

以下是 Vite 配置对应的 Rsbuild 配置：

说明：

• 上述表格尚未覆盖到 Vite 的所有配置，欢迎补充。

#环境变量

Vite 默认会将 VITE_ 开头的环境变量注入到 client 代码中，而 Rsbuild 默认会注入 PUBLIC_ 开头的环境变量（参考 public 变量）。

为了兼容 Vite 的行为，你可以手动调用 Rsbuild 提供的 loadEnv 方法来读取 VITE_ 开头的环境变量，并通过 source.define 配置项注入到 client 代码中。

import { defineConfig, loadEnv } from '@rsbuild/core';

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

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

Rsbuild 默认注入了以下 环境变量：

• import.meta.env.MODE
• import.meta.env.BASE_URL
• import.meta.env.PROD
• import.meta.env.DEV
• import.meta.env.SSR

#预设类型

Vite 通过 vite-env.d.ts 文件提供了一些预设的类型定义，迁移到 Rsbuild 时，你可以使用 @rsbuild/core 提供的 预设类型：

/// <reference types="vite/client" />
/// <reference types="@rsbuild/core/types" />

#Web Workers

从 Vite 的 worker query 导入迁移到 Rsbuild 时，Rsbuild 支持 ?worker 和 ?worker&inline：

import Worker from './worker.ts?worker';
import InlineWorker from './worker.ts?worker&inline';

Rsbuild 不支持 Vite 的 ?worker&url query 后缀。如果你使用它来创建 dedicated worker，可以迁移为标准的 new Worker() 构造器语法：

const worker = new Worker(new URL('./worker.ts', import.meta.url), {
  type: 'module',
});

Rsbuild 也不支持 Vite 的 ?sharedworker、?sharedworker&inline 或 ?sharedworker&url query 后缀。为了保留 shared worker 的行为，请使用标准的 new SharedWorker() 构造器语法：

const sharedWorker = new SharedWorker(new URL('./worker.ts', import.meta.url), {
  type: 'module',
});

构造器语法也允许你传入标准的 WorkerOptions 或 SharedWorkerOptions，例如 name、type 和 credentials。更多用法请参考 Web Workers。

#Glob import

Rsbuild >= 2.0.8 已兼容 import.meta.glob()，因此从 Vite 迁移到 Rsbuild 时可以保留原有代码。

#vite-tsconfig-paths

Rsbuild 开箱即用地支持 TypeScript 的 paths 选项作为 alias 别名，因此你可以直接移除 vite-tsconfig-paths 依赖。

参考 路径别名 来了解更多。

#迁移 Vite 插件

参考 Vite 插件 了解如何迁移 Vite 插件。

#验证结果

完成以上步骤后，你已经完成了从 Vite 到 Rsbuild 的基本迁移，此时可以执行 npm run dev 命令来尝试启动开发服务器。

如果在构建过程中发现问题，请根据错误日志进行调试，或者查看 Vite 配置，检查是否有一些必须的配置未被迁移到 Rsbuild。

#内容补充

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

Rsbuild 的文档位于 rsbuild/website 目录。