环境配置
系统要求
在开始使用 Vite 之前，请确保你的开发环境满足以下要求：
- Node.js: 版本 20.19+ 或 22.12+
- 包管理器: npm、yarn、pnpm 或 bun（推荐 pnpm）
- 操作系统: Windows、macOS 或 Linux
检查 Node.js 版本
node --version
如果版本过低，请前往 Node.js 官网 下载并安装 LTS 版本。
创建 Vite 项目
Vite 提供了多种方式来创建新项目：
方式一：交互式创建（推荐）
npm create vite@latest
执行后会提示你选择：
- 项目名称
- 框架（Vanilla、Vue、React、Preact、Lit、Svelte、Solid、Qwik）
- 语言变体（JavaScript 或 TypeScript）
方式二：命令行参数创建
# 创建 Vue + TypeScript 项目
npm create vite@latest my-vue-app -- --template vue-ts
# 创建 React 项目
npm create vite@latest my-react-app -- --template react
# 创建 React + TypeScript 项目
npm create vite@latest my-react-app -- --template react-ts
# 创建纯 JavaScript 项目
npm create vite@latest my-vanilla-app -- --template vanilla
支持的模板
| 模板 | 说明 |
|---|---|
vanilla | 纯 JavaScript |
vanilla-ts | 纯 TypeScript |
vue | Vue 3 |
vue-ts | Vue 3 + TypeScript |
react | React |
react-ts | React + TypeScript |
react-swc | React + SWC（更快的编译） |
react-swc-ts | React + SWC + TypeScript |
preact | Preact |
preact-ts | Preact + TypeScript |
lit | Lit |
lit-ts | Lit + TypeScript |
svelte | Svelte |
svelte-ts | Svelte + TypeScript |
solid | SolidJS |
solid-ts | SolidJS + TypeScript |
qwik | Qwik |
qwik-ts | Qwik + TypeScript |
方式三：在当前目录创建
npm create vite@latest . -- --template vue
使用 . 作为项目名会在当前目录直接创建项目。
项目初始化流程
创建项目后，需要安装依赖并启动开发服务器：
# 进入项目目录
cd my-project
# 安装依赖
npm install
# 启动开发服务器
npm run dev
默认情况下，开发服务器会在 http://localhost:5173 启动。
项目结构
一个典型的 Vite 项目结构如下：
my-project/
├── index.html # HTML 入口文件
├── package.json # 项目配置和依赖
├── vite.config.js # Vite 配置文件
├── public/ # 静态资源（不会被处理）
│ └── favicon.ico
└── src/ # 源代码
├── main.js # 入口 JS 文件
├── style.css # 全局样式
└── assets/ # 资源文件（会被处理）
└── logo.png
关键文件说明
index.html
Vite 项目的入口是 index.html 文件，它位于项目根目录而非 public 目录。这是有意为之的：在开发期间，Vite 是一个服务器，index.html 是应用的入口点。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Vite App</title>
</head>
<body>
<div id="app"></div>
<!-- 引用主入口文件 -->
<script type="module" src="/src/main.js"></script>
</body>
</html>
Vite 将 index.html 视为源代码和模块图的一部分。它会解析 <script type="module" src="..."> 引用的 JavaScript 源代码，甚至内联的 <script type="module"> 和通过 <link href> 引用的 CSS 也能享受 Vite 的特定功能。
vite.config.js
Vite 的配置文件，用于自定义构建行为：
import { defineConfig } from 'vite'
export default defineConfig({
// 配置选项
server: {
port: 3000,
},
build: {
outDir: 'dist',
},
})
常用命令
Vite 项目通常包含以下 npm 脚本：
{
"scripts": {
"dev": "vite", // 启动开发服务器
"build": "vite build", // 构建生产版本
"preview": "vite preview" // 预览生产构建
}
}
开发服务器
# 启动开发服务器（默认端口 5173）
npm run dev
# 指定端口
npx vite --port 3000
# 自动打开浏览器
npx vite --open
# 指定主机（允许外部访问）
npx vite --host
生产构建
# 构建生产版本
npm run build
# 构建并指定模式
npx vite build --mode production
# 构建并指定输出目录
npx vite build --outDir dist
预览构建
# 预览生产构建（在本地启动服务器预览构建结果）
npm run preview
# 指定端口预览
npx vite preview --port 4173
手动安装 Vite
如果你不想使用 create-vite，也可以手动安装：
# 创建项目目录
mkdir my-project
cd my-project
# 初始化 package.json
npm init -y
# 安装 Vite 作为开发依赖
npm install -D vite
# 创建 index.html
echo '<!doctype html>
<html>
<head>
<title>My Vite App</title>
</head>
<body>
<h1>Hello Vite!</h1>
<script type="module" src="/src/main.js"></script>
</body>
</html>' > index.html
# 创建 src 目录和入口文件
mkdir src
echo 'console.log("Hello Vite!")' > src/main.js
# 启动开发服务器
npx vite
在线体验 Vite
如果不想在本地安装，可以在 StackBlitz 上在线体验 Vite：
- 访问 vite.new 选择框架模板
- 或直接访问特定模板：
https://vite.new/vue- Vue 模板https://vite.new/react- React 模板https://vite.new/react-ts- React + TypeScript 模板
常见问题
端口被占用
如果默认端口 5173 被占用，Vite 会自动尝试下一个可用端口。也可以手动指定：
npx vite --port 3000
权限问题（Linux/macOS）
如果在运行命令时遇到权限错误，可能需要修改 npm 的默认目录或使用 npx：
# 使用 npx（推荐）
npx vite
# 或修改 npm 目录权限
sudo chown -R $(whoami) ~/.npm
Windows 下的路径问题
在 Windows PowerShell 中使用 create-vite 时，可能需要额外的双横线：
# PowerShell 需要额外的双横线
npm create vite@latest my-app -- --template vue
小结
本章我们学习了：
- 系统要求：Node.js 20.19+ 或 22.12+
- 项目创建：使用
npm create vite@latest快速创建项目 - 项目结构：了解
index.html、vite.config.js等关键文件 - 常用命令：
dev、build、preview的使用 - 手动安装：如何从零开始配置 Vite 项目
现在你的开发环境已经准备就绪，下一章我们将深入学习 Vite 的配置文件。