Vite#

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

安装依赖#

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

• 移除 Vite 的依赖：

npm remove vite

• 安装 Rsbuild 的依赖：

npm add @rsbuild/core -D

更新 npm scripts#

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

{
  "scripts": {
-   "dev": "vite",
-   "build": "vite build",
-   "preview": "vite preview"
+   "dev": "rsbuild dev",
+   "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.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，你可以通过 environments 和 source.define 配置项来设置：

export default defineConfig({
  environments: {
    web: {
      source: {
        define: {
          'import.meta.env.SSR': JSON.stringify(false),
        },
      },
    },
    node: {
      source: {
        define: {
          'import.meta.env.SSR': JSON.stringify(true),
        },
      },
      output: {
        target: 'node',
      },
    },
  },
});

预设类型#

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

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

Glob Import#

Vite 提供了 import.meta.glob() 来批量导入模块。

迁移到 Rsbuild 时，你可以使用 Rspack 的 import.meta.webpackContext 函数代替：

• Vite:

const modules = import.meta.glob('./dir/*.js');

for (const path in modules) {
  modules[path]().then((mod) => {
    console.log(path, mod);
  });
}

• Rsbuild:

const context = import.meta.webpackContext('./dir', {
  // 是否搜索子目录
  recursive: false,
  regExp: /\.js$/,
});

for (const path of context.keys()) {
  const mod = context(path);
  console.log(path, mod);
}

验证结果#

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

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

内容补充#

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

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