首页
/ Vite 快速上手指南：从脚手架、开发服务器到 CLI 的完整实践

Vite 快速上手指南：从脚手架、开发服务器到 CLI 的完整实践

2026-09-04 10:29:13作者：咎岭娴Homer
vite
Next generation frontend tooling. It's fast!
项目地址：https://gitcode.com/GitHub_Trending/vi/vite

本文基于 Vite 官方入门文档（docs/guide/index.md）编写，系统讲解 Vite 的核心构成、浏览器支持策略、项目创建方式（create-vite 脚手架与手动安装）、index.html 作为入口的根目录模型，以及 dev / build / preview 三大 CLI 命令的使用细节。读完本文，你将能够独立创建、运行并定制一个 Vite 项目，理解开发服务器为何以 index.html 为应用入口，并知道如何验证 CLI 参数与安装脚本行为（仓库内配套有针对 create-vite 与 CLI 的自动化测试）。

一、Vite 是什么：开发服务器 + 构建命令

Vite（法语中"快"的意思，发音接近 "veet"）是一个构建工具，目标是为现代 Web 项目提供更快速、更精简的开发体验。它由两个主要部分组成：

  • 开发服务器（Dev Server）：基于原生 ES 模块提供丰富的功能增强，例如极快的热模块替换（HMR，Hot Module Replacement）。更多特性见 Features Guide。
  • 构建命令（Build Command）：使用 Rolldown 对你的代码进行打包，并预先配置好以输出高度优化的生产环境静态资源。

Vite 是"有主见的"（opinionated），开箱即用地提供合理的默认值。对框架的支持、与工具的集成通过插件实现（参见 Using Plugins）；当需要让 Vite 适配项目时，可通过配置章节进行定制。

此外，Vite 通过 Plugin API 和 JavaScript API 高度可扩展，并提供完整的 TypeScript 类型支持。关于项目背后的设计思路，可参阅 Why Vite。

从源码结构看，vite 包本身是一个 Native-ESM 的构建工具（packages/vite/package.json 中 description 为 "Native-ESM powered web dev build tool"，当前版本 8.2.2），bin/vite.js 暴露了 vite 可执行入口，导出的子路径还包括 ./client、./module-runner、./internal 等。

二、浏览器支持策略

开发环境：Vite 假设使用现代浏览器，即浏览器支持绝大多数最新的 JavaScript 与 CSS 特性。为此 Vite 将语法转换目标设为 esnext，避免语法降级，让 Vite 以尽可能接近原始源码的形态提供模块。Vite 会注入一些运行时代码以使开发服务器工作，这些代码只使用各主版本发布时（当前主版本为 2026-01-01）处于 Baseline "Newly Available" 状态的浏览器特性。

生产构建：默认目标是各主版本发布时固定的 Baseline "Widely Available" 浏览器版本。当前主版本对应约 2023 年中发布的浏览器版本。该目标可以通过配置降低；如需支持更老的遗留浏览器，可以使用官方的 @vitejs/plugin-legacy 插件（源码就在本仓库 packages/plugin-legacy 中）。更多细节见 Building for Production。

三、在线试用 Vite

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

支持的模板预设（JavaScript / TypeScript 双列）：

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

这些模板在仓库中真实存在，例如 packages/create-vite/template-vanilla、packages/create-vite/template-react 等，可以逐一查看模板的完整文件构成。

四、使用 create-vite 脚手架创建第一个项目

按包管理器选择对应的脚手架命令：

# npm
npm create vite@latest

# Yarn
yarn create vite

# pnpm
pnpm create vite

# Bun
bun create vite

# Deno
deno init --npm vite

然后按提示操作即可。

Node.js 版本要求：Vite 要求 Node.js 20.19+ 或 22.12+。这一点在仓库中得到直接印证——packages/vite/package.json 与 packages/create-vite/package.json 中的 engines 字段均为：

{
  "engines": {
    "node": "^20.19.0 || >=22.12.0"
  }
}

部分模板可能需要更高的 Node.js 版本才能工作，若包管理器给出警告请升级 Node.js。

4.1 通过命令行选项直接指定模板

也可以在脚手架命令中直接指定项目名与模板。例如创建一个 Vite + Vue 项目：

# npm（npm 7+ 需要额外的双连字符）
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-compiler、react-ts、react-compiler-ts、preact、preact-ts、lit、lit-ts、svelte、svelte-ts、solid、solid-ts、qwik、qwik-ts。

几个实用技巧（均可在 packages/create-vite/src/index.ts 的 helpMessage 与参数解析逻辑中得到验证）：

  • 项目名使用 . 表示在当前目录创建；
  • 使用 --no-interactive 标志跳过所有交互提示，适合脚本化场景（源码中非交互模式下默认模板为 vanilla-ts）；
  • 其他支持的选项包括：-t, --template 指定模板、-i, --immediate / --no-immediate 创建后立即安装依赖并启动开发服务器、--overwrite 在目标目录非空时删除已有文件、--eslint / --no-eslint 在 React 模板中使用 ESLint 代替 Oxlint（仅对 React 模板有效）。

从源码结构看，init() 函数（packages/create-vite/src/index.ts）的执行流程为：解析项目名与目标目录 → 处理目标目录非空的情况（yes/no/ignore 三种选择）→ 校验包名 → 选择框架与变体（FRAMEWORKS 数组同时内置了 Vue/React/Svelte 等官方生态的"自定义命令"变体，如 Nuxt、SvelteKit 等，会以 customCommand 方式转交外部脚手架）→ 复制 template-${template} 目录下的文件并替换 index.html 的 <title> 与 package.json 的 name → 可选地执行立即安装（install() + start()）。值得一提的是，源码还会通过 @vercel/detect-agent 检测 AI Agent 环境，并在 Agent 中提示使用 create-vite <DIRECTORY> --no-interactive --template <TEMPLATE> 一次性完成创建。

仓库内还有针对脚手架的端到端测试：packages/create-vite/tests，测试中通过 _VITE_TEST_CLI 环境变量跳过真实的依赖安装步骤，验证脚手架落盘行为。

4.2 社区模板

create-vite 是针对主流框架的官方基础模板工具。若需要其他工具或框架的模板，可以查阅 Awesome Vite 中社区维护的模板列表；也可以使用 tiged 等工具从任意仓库拉取模板：

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

npm install
npm run dev

（假定项目默认分支为 main。）

五、手动安装 Vite

如果不想用脚手架，可以在现有项目中手动安装 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 将服务于 http://localhost:5173。

六、index.html 与项目根目录

你可能已经注意到，在 Vite 项目中 index.html 是"前台中心化"的，而不是藏在 public 目录里。这是有意为之：开发阶段 Vite 本质上是一个服务器，index.html 就是你的应用入口。

具体而言：

  • Vite 把 index.html 当作源码和模块图的一部分。它会解析其中引用你 JS 源码的 <script type="module" src="...">；内联的 <script type="module"> 以及通过 <link href> 引用的 CSS 同样享受 Vite 的特性；
  • index.html 中的 URL 会被自动重定基（rebased），因此不需要 %PUBLIC_URL% 之类的特殊占位符。

官方模板中的入口写法可以参见 packages/create-vite/template-vanilla/index.html：

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite + JS</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

与静态 HTTP 服务器类似，Vite 有"根目录（root directory）"的概念——你的文件都从该目录提供，后续文档中会写作 <root>。源码中的绝对 URL 以项目根为基准解析，因此你可以像操作普通静态文件服务器一样编写代码（而实际能力远强于静态服务器）。Vite 还能处理解析到根目录之外文件系统位置的依赖，这让它在 monorepo 场景下同样可用。

Vite 还支持多页面应用（MPA），允许多个 .html 作为入口，详见 Building for Production 的 Multi-Page App 小节。

指定替代根目录

运行 vite 时默认以当前工作目录为根。可以用 vite serve some/sub/dir 指定替代根目录。注意 Vite 还会在项目根中解析配置文件（即 vite.config.js），因此改变根目录时需要相应移动配置文件（见配置章节）。

从 CLI 源码看（packages/vite/src/node/cli.ts），默认命令正是带 [root] 位置参数的 vite [root]（别名 serve），build [root] 与 preview [root] 也接受同样的位置参数，这与文档描述一一对应。

七、命令行接口（CLI）

在安装了 Vite 的项目中，你可以在 npm scripts 里使用 vite 二进制，或直接以 npx vite 运行。脚手架生成的项目默认 npm scripts 如下：

{
  "scripts": {
    "dev": "vite",         // 启动开发服务器，别名：`vite dev`、`vite serve`
    "build": "vite build", // 生产构建
    "preview": "vite preview" // 本地预览生产构建
  }
}

可以附加 --port、--open 等 CLI 选项；完整列表可在项目内运行 npx vite --help 查看。

从 packages/vite/src/node/cli.ts 中可以确认三大命令的完整选项集：

  • 全局选项（对所有子命令生效）：-c, --config <file> 指定配置文件、--base <path> 公共基础路径（默认 /）、-l, --logLevel <level>（info | warn | error | silent）、--clearScreen 控制日志清屏、-d, --debug [feat] 与 -f, --filter <filter> 调试日志、-m, --mode <mode> 设置环境模式等；
  • vite [root]（serve）：--host [host] 指定主机名、--port <port> 指定端口、--open [path] 启动时打开浏览器、--cors 启用 CORS、--strictPort 端口被占用时退出；
  • vite build [root]：--outDir <dir> 输出目录（默认 dist）、--manifest [name] 输出构建清单 JSON、--ssrManifest [name] 输出 SSR 清单、-w, --watch 文件变化时重建等；
  • vite preview [root]：本地预览生产构建产物。

完整 CLI 文档见 Command Line Interface。

八、使用未发布的 Vite 提交

如果等不及新发布而想测试最新功能，有两种方式：

方式一：按 commit 安装。将 SHA 替换为 Vite 主分支的任意 commit SHA（注意：仅最近一个月内产生的 commit 安装可用，更早的会被清理）：

# 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

方式二：本地克隆构建并链接（需要 pnpm）：

git clone https://github.com/vitejs/vite.git
cd vite
pnpm install
cd packages/vite
pnpm run build
pnpm link   # 此步可用你偏好的包管理器

然后到你的 Vite 项目中运行 pnpm link vite（或你用于全局链接 vite 的包管理器对应命令），重启开发服务器即可。

关于 Vite 的发布节奏与流程，见 Releases 文档。

提示：若要替换依赖间接（transitively）使用的 Vite 版本，应使用 npm 的 overrides 或 pnpm 的 overrides 配置。

九、延伸阅读与社区资源

如果你有疑问或需要帮助，可以通过 Discord 与 GitHub Discussions 联系 Vite 社区。仓库内的 CONTRIBUTING.md 则面向希望参与开发的贡献者。

十、小结

场景 命令 / 方式
交互式创建项目 npm create vite@latest 后跟随提示
非交互式创建项目 npm create vite@latest my-app -- --template vue（npm 7+ 需双连字符）
手动安装并启动 npm install -D vite && npx vite，index.html 位于 http://localhost:5173
指定根目录 vite serve some/sub/dir
生产构建 / 预览 vite build / vite preview
查看全部选项 npx vite --help

Vite 的核心心智模型可以浓缩为三句话：开发时它是模块服务器，index.html 是入口而非产物；生产时它是 Rolldown 打包管线，输出高度优化的静态资源；一切定制通过配置与插件完成。结合本文的命令与仓库中的源码路径，你可以快速完成从建项、开发到构建预览的完整闭环。

vite
Next generation frontend tooling. It's fast!
项目地址：https://gitcode.com/GitHub_Trending/vi/vite
登录后查看全文

相关内容推荐

1 Vue CLI 使用教程2 **推荐使用：Vue CLI——搭建Vue应用的快速启动器**3 Vite 核心架构与使用指南：从 Dev Server、Rolldown 构建到插件体系全解析4 Vite + Qwik 模板：用 create-vite 搭建 CSR 模式的 Qwik 应用5 【亲测免费】 Vant Demo 安装与配置完全指南6 【亲测免费】 将Webpack迁移到Vite的实战指南：使用`webpack-to-vite`7 Omi - 高性能Web组件框架实战指南8 使用指南：vue-cli-plugin-vite快速集成教程9 Vite 5.0 发布解析：Rollup 4、API 清理与 server.warmup 启动提速指南10 【亲测免费】 银河麒麟v10前端环境安装指南
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

rtk 的 /diagnose 命令：为 RTK × Claude Code 集成构建一套可复用的环境诊断流程OpenScreen macOS 原生光标捕获测试管线：Helper 构建、冒烟测试与 Sidecar 验证实战Zed CLI（cli crate）本地测试实战：从 `cargo build -p zed` 到跨平台启动器的源码级剖析Flutter 仓库 Dart 代码编辑守则：dart analyze / dart format 收尾流程与 material/cupertino 层依赖隔离Umi-OCR HTTP 接口完全手册：图片 OCR、PDF 文档识别、二维码与 argv 接口的实战接入指南caveman 公共包发布流水线：从注解标签到 npm/PyPI 可信发布的完整机制Upscayl 进阶实战指南：GPU ID 选择、日志排查、自定义 NCNN 模型与 Scale 缩放参数Polars Parquet 读取器源码解析：嵌套类型反序列化与 Definition Levels 位图等价优化Bruno 跨平台工程实践：Electron 应用在 macOS、Windows 与 Linux 上的文件系统、进程与路径处理指南ECC bun-runtime Skill 实战指南：Bun 运行时选型、Node 迁移与 Agent 工作流集成

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
590
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
904
1.82 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
docsdocs
暂无描述
Markdown
889
5.78 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.52 K
1.01 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.33 K
1.45 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
982
503
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
540
384