入门指南

概览

Vite（法语意为“快速”，发音为 /viːt/，类似“veet”）是一种构建工具，旨在为现代 Web 项目提供更快、更精简的开发体验。它主要由两部分组成：

• 一个开发服务器，它基于 原生 ES 模块 提供了 丰富的特性增强，例如极速的 模块热更新 (HMR)。

• 一套构建指令，使用 Rolldown 打包你的代码，并预先配置好，以便输出高度优化的生产环境静态资源。

Vite 坚持“开箱即用”的理念，并提供合理的默认配置。阅读 特性指南 以了解其能力。通过 插件，可以实现对各种框架的支持或与其他工具的集成。配置章节 则解释了如何在必要时针对你的项目调整 Vite。

Vite 还通过其 插件 API 和 JavaScript API 提供了高度的可扩展性，并拥有完整的类型支持。

你可以在 为什么选 Vite 章节中了解该项目背后的核心理念。

通过 Scrimba 的交互式教程学习 Vite

浏览器支持

在开发过程中，Vite 假设你使用现代浏览器。这意味着浏览器支持大部分最新的 JavaScript 和 CSS 特性。因此，Vite 将 esnext 设置为转译目标。这防止了语法降级，让 Vite 能够尽可能地以接近源码的方式提供模块。Vite 会注入一些运行时代码以使开发服务器正常工作。这些代码使用了在每个大版本发布时（针对此大版本为 2026-01-01）在 Baseline 中“新可用 (Newly Available)”的特性。

对于生产构建，Vite 默认的目标是 Baseline 中“广泛可用 (Widely Available)”的浏览器。这些浏览器是指至少 2.5 年前发布的版本。该目标可以通过配置进行降低。此外，可以通过官方的 @vitejs/plugin-legacy 插件支持旧版浏览器。更多详情请参见 构建生产版本 章节。

在线尝试 Vite

你可以在 StackBlitz 上在线尝试 Vite。它直接在浏览器中运行基于 Vite 的构建设置，因此与本地环境几乎相同，且无需在机器上安装任何东西。你可以访问 vite.new/{template} 来选择要使用的框架。

支持的模板预设包括：

JavaScript	TypeScript
vanilla	vanilla-ts
vue	vue-ts
react	react-ts
preact	preact-ts
lit	lit-ts
svelte	svelte-ts
solid	solid-ts
qwik	qwik-ts

搭建你的第一个 Vite 项目

npm

$ npm create vite@latest

Yarn

$ yarn create vite

pnpm

$ pnpm create vite

Bun

$ bun create vite

Deno

$ deno init --npm vite

然后按照提示操作即可！

观看 Scrimba 上的交互式课程

兼容性注意

Vite 需要 Node.js 20.19+ 或 22.12+ 版本。不过，有些模板可能需要更高版本的 Node.js 才能运行，如果你的包管理器对此发出警告，请升级你的 Node.js 版本。

使用 create-vite 的命令行选项

你还可以通过额外的命令行选项直接指定项目名称和要使用的模板。例如，要搭建一个 Vite + Vue 项目，运行：

npm

# npm 7+, extra double-dash is needed:
$ npm create vite@latest my-vue-app -- --template vue

Yarn

$ yarn create vite my-vue-app --template vue

pnpm

$ pnpm create vite my-vue-app --template vue

Bun

$ bun create vite my-vue-app --template vue

Deno

$ deno init --npm vite my-vue-app --template vue

有关每个支持模板的详细信息，请参阅 create-vite：vanilla、vanilla-ts、vue、vue-ts、react、react-ts、react-swc、react-swc-ts、preact、preact-ts、lit、lit-ts、svelte、svelte-ts、solid、solid-ts、qwik、qwik-ts。

你可以使用 . 作为项目名称，在当前目录下进行搭建。

若要创建一个无需交互式提示的项目，可以使用 --no-interactive 标志。

社区模板

create-vite 是一个用于从主流框架的基础模板快速启动项目的工具。请查看 Awesome Vite 以获取更多 社区维护的模板，其中包含了其他工具或针对不同框架的配置。

对于位于 https://github.com/user/project 的模板，你可以通过在项目 URL 的 github 后面添加 .stackblitz（即 https://github.stackblitz.com/user/project）在线进行尝试。

你也可以使用像 tiged 这样的工具来利用其中一个模板搭建项目。假设项目托管在 GitHub 上且使用 main 作为默认分支，你可以通过以下方式创建本地副本：

npx tiged user/project my-project
cd my-project

npm install
npm run dev

手动安装

在你的项目中，你可以通过以下命令安装 vite CLI：

npm

$ npm install -D vite

Yarn

$ yarn add -D vite

pnpm

$ pnpm add -D vite

Bun

$ bun add -D vite

Deno

$ deno add -D npm:vite

并创建一个如下所示的 index.html 文件：

<p>Hello Vite!</p>

然后在终端中运行相应的 CLI 命令：

npm

$ npx vite

Yarn

$ yarn vite

pnpm

$ pnpm vite

Bun

$ bunx vite

Deno

$ deno run -A npm:vite

index.html 将会在 https://:5173 被服务。

index.html 与项目根目录

你可能已经注意到，在 Vite 项目中，index.html 处于核心地位，而不是被隐藏在 public 文件夹中。这是有意为之的：在开发过程中，Vite 是一个服务器，而 index.html 是你应用程序的入口点。

Vite 将 index.html 视为源代码，并将其作为模块图的一部分。它会解析引用 JavaScript 源码的 <script type="module" src="...">。甚至内联的 <script type="module"> 和通过 <link href> 引用的 CSS 也都享有 Vite 的特定功能。此外，index.html 中的 URL 会被自动处理，因此无需特殊的 %PUBLIC_URL% 占位符。

类似于静态 HTTP 服务器，Vite 拥有“根目录”的概念，你的文件将从这里被服务。在后续文档中，它会被称为 <root>。源代码中的绝对路径将以项目根目录为基准进行解析，因此你可以像使用普通的静态文件服务器一样编写代码（只是功能强大得多！）。Vite 还能够处理指向根目录之外文件系统的依赖项，这使得它在基于 Monorepo 的设置中也能使用。

Vite 还支持具有多个 .html 入口点的 多页面应用。

指定备用根目录

运行 vite 会以当前工作目录作为根目录启动开发服务器。你可以通过 vite serve some/sub/dir 指定一个备用根目录。请注意，Vite 也会在项目根目录中解析 其配置文件 (即 vite.config.js)，因此如果更改了根目录，你也需要移动该文件。

命令行界面

在安装了 Vite 的项目中，你可以在 npm 脚本中使用 vite 二进制文件，或者直接通过 npx vite 运行。以下是 Vite 项目脚手架中的默认 npm 脚本：

package.json

{
  "scripts": {
    "dev": "vite", // start dev server, aliases: `vite dev`, `vite serve`
    "build": "vite build", // build for production
    "preview": "vite preview" // locally preview production build
  }
}

你可以指定额外的 CLI 选项，例如 --port 或 --open。欲获取完整的 CLI 选项列表，请在你的项目中运行 npx vite --help。

了解更多关于 命令行界面 的信息。

使用未发布的提交

如果你等不及新版本的发布来测试最新功能，可以通过 https://pkg.pr.new 安装特定提交版本的 Vite。

npm

$ npm install -D https://pkg.pr.new/vite@SHA

Yarn

$ yarn add -D https://pkg.pr.new/vite@SHA

pnpm

$ pnpm add -D https://pkg.pr.new/vite@SHA

Bun

$ bun add -D https://pkg.pr.new/vite@SHA

将 SHA 替换为 Vite 提交记录的 SHA。请注意，只有最近一个月内的提交才有效，因为旧的提交发布会被清理。

或者，你也可以将 Vite 仓库 克隆到本地机器，然后自行构建和链接（需要 pnpm）。

git clone https://github.com/vitejs/vite.git
cd vite
pnpm install
cd packages/vite
pnpm run build
pnpm link # use your preferred package manager for this step

然后转到你的 Vite 项目并运行 pnpm link vite（或者你之前用于全局链接 vite 的包管理器）。现在重启开发服务器，开始体验最前沿的功能！

要了解更多关于 Vite 何时以及如何进行版本发布的信息，请查看 发布说明 文档。

依赖项使用 Vite

要替换依赖项间接使用的 Vite 版本，你应该使用 npm overrides 或 pnpm overrides。

社区

如果你有疑问或需要帮助，请在 Discord 和 GitHub Discussions 上联系社区。