环境配置

系统要求

在开始使用 Vite 之前，请确保你的开发环境满足以下要求：

Node.js: 版本 20.19+ 或 22.12+
包管理器: npm、yarn、pnpm、bun 或 deno
操作系统: Windows、macOS 或 Linux

某些模板可能需要更高版本的 Node.js，如果你的包管理器发出警告，请升级 Node.js。

Vite 8 使用 Rolldown 和 Oxc 作为统一的构建工具链，这些工具用 Rust 编写，提供了极高的性能。你不需要单独安装这些工具，它们会作为 Vite 的依赖自动安装。

注意：Vite 8 的安装包比 Vite 7 大约 15 MB，主要来自：

~10 MB Lightning CSS：现在作为常规依赖提供更好的 CSS 压缩
~5 MB Rolldown：Rust 编译的二进制文件，性能优化优先于文件大小

检查 Node.js 版本

node --version

如果版本过低，请前往 Node.js 官网下载并安装 LTS 版本。

包管理器支持

Vite 支持所有主流包管理器：

包管理器	创建项目命令	安装依赖命令
npm	`npm create vite@latest`	`npm install`
yarn	`yarn create vite`	`yarn`
pnpm	`pnpm create vite`	`pnpm install`
bun	`bun create vite`	`bun install`
deno	`deno init --npm vite`	`deno install`

创建 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

使用 . 作为项目名会在当前目录直接创建项目。

方式四：非交互式创建

如果不想进行交互式选择，可以使用 --no-interactive 标志直接创建：

npm create vite@latest my-app -- --template vue --no-interactive

方式五：使用社区模板

除了官方模板，你还可以使用社区维护的模板。Awesome Vite 收集了大量社区模板，包含其他工具集成或针对不同框架的配置。

对于 GitHub 上的模板项目，你可以：

在线体验：将 github 替换为 github.stackblitz，例如：
- 原地址：https://github.com/user/project
- 在线体验：https://github.stackblitz.com/user/project

本地克隆：使用 tiged 等工具：

npx tiged user/project my-project
cd my-project
npm install
npm run dev

项目初始化流程

创建项目后，需要安装依赖并启动开发服务器：

# 进入项目目录
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

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 的特定功能。此外，index.html 中的 URL 会自动重写，无需使用特殊的 %PUBLIC_URL% 占位符。

项目中所有的 HTML 文件都可以通过相应的目录路径直接访问：

文件路径	访问地址
`<root>/index.html`	`http://localhost:5173/`
`<root>/about.html`	`http://localhost:5173/about.html`
`<root>/blog/index.html`	`http://localhost:5173/blog/index.html`

HTML 资源处理

Vite 会处理 HTML 中引用的资源。HTML 文件在 Vite 项目中处于核心位置，作为应用的入口点。这与传统打包工具将 index.html 放在 public 目录的做法不同——在开发期间，Vite 是一个服务器，index.html 是应用的入口点。

支持的元素和属性：

元素	属性
`<audio>`	`src`
`<embed>`	`src`
`<img>`	`src`, `srcset`
`<image>`	`href`, `xlink:href`
`<input>`	`src`
`<link>`	`href`, `imagesrcset`
`<object>`	`data`
`<script>`	`type="module"` 时的 `src`
`<source>`	`src`, `srcset`
`<track>`	`src`
`<use>`	`href`, `xlink:href`
`<video>`	`src`, `poster`
`<meta>`	`content`（特定条件）

<meta> 标签的特殊处理：

<meta> 标签的 content 属性仅在以下条件下会被处理：

name 属性匹配以下值之一：
- msapplication-tileimage
- msapplication-square70x70logo
- msapplication-square150x150logo
- msapplication-wide310x150logo
- msapplication-square310x310logo
- msapplication-config
- twitter:image
property 属性匹配以下值之一：
- og:image
- og:image:url
- og:image:secure_url
- og:audio
- og:audio:secure_url
- og:video
- og:video:secure_url

这些通常是用于社交分享预览和 Windows 磁贴图标的元数据标签。

如果需要跳过某些元素的处理（例如引用外部 CDN 资源），可以添加 vite-ignore 属性：

<!-- 不处理这个外部资源 -->
<script src="https://cdn.example.com/lib.js" vite-ignore></script>

<!-- 外部字体 CDN -->
<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" vite-ignore />

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

CLI 命令详解

开发服务器选项

选项	说明
`--host [host]`	指定主机名，设为 `true` 或 `0.0.0.0` 可监听所有地址
`--port <port>`	指定端口号
`--open [path]`	启动时自动打开浏览器
`--cors`	启用 CORS
`--strictPort`	端口被占用时直接退出，而非自动尝试下一个可用端口
`--force`	强制忽略缓存重新预构建依赖
`-c, --config <file>`	使用指定的配置文件
`--base <path>`	公共基础路径（默认 `/`）
`-l, --logLevel <level>`	日志级别：`info` \| `warn` \| `error` \| `silent`
`--clearScreen`	是否在日志输出时清屏
`--configLoader <loader>`	配置加载方式：`bundle` \| `runner` \| `native`
`--profile`	启动内置 Node.js 分析器
`-d, --debug [feat]`	显示调试日志
`-m, --mode <mode>`	设置环境模式

构建选项

选项	说明
`--target <target>`	转译目标（默认 `"modules"`）
`--outDir <dir>`	输出目录（默认 `dist`）
`--assetsDir <dir>`	静态资源目录（默认 `assets`）
`--assetsInlineLimit <number>`	静态资源 base64 内联阈值（默认 4096 字节）
`--ssr [entry]`	为 SSR 构建指定入口
`--sourcemap [output]`	输出 source map
`--minify [minifier]`	压缩方式：`esbuild` \| `terser`
`--manifest [name]`	生成构建清单 JSON
`--ssrManifest [name]`	生成 SSR 清单 JSON
`--emptyOutDir`	强制清空输出目录
`-w, --watch`	监听文件变化重新构建

已废弃的命令

vite optimize 命令已被废弃。预构建过程现在会自动运行，无需手动调用。

手动安装 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 项目

系统要求​

检查 Node.js 版本​

包管理器支持​

创建 Vite 项目​

方式一：交互式创建（推荐）​

方式二：命令行参数创建​

支持的模板​

方式三：在当前目录创建​

方式四：非交互式创建​

方式五：使用社区模板​

项目初始化流程​

项目结构​

关键文件说明​

index.html​

HTML 资源处理​

vite.config.js​

常用命令​

开发服务器​

生产构建​

预览构建​

CLI 命令详解​

开发服务器选项​

构建选项​

已废弃的命令​

手动安装 Vite​

在线体验 Vite​

常见问题​

端口被占用​

权限问题（Linux/macOS）​

Windows 下的路径问题​

小结​