Vue.js 新手入门：怎么使用 Vite 快速搭建第一个项目

一、准备环境：检查并安装 Node.js

Vite 和 Vue 3 的开发依赖 Node.js 运行环境及其自带的包管理器 npm。在正式运行脚手架之前，需要先确认你的计算机上已安装了兼容版本的 Node.js。

打开系统自带的终端（macOS / Linux 用户使用 Terminal，Windows 用户推荐使用 PowerShell 或 Windows Terminal），输入以下命令检查版本：

node -v
npm -v

二、理解原理：为什么搭建 Vue 项目首选 Vite

在进入创建命令之前，先理解 Vite 为什么比传统脚手架工具（如早期的 Vue CLI / Webpack）更轻快，有助于在后续开发中建立正确的工程化认知。

过去基于 Webpack 的开发服务器，在启动前必须从入口文件开始，顺着所有的 import 语法爬梳项目里的所有文件，打包捆绑成数个体积庞大的内存文件，随后才开启 HTTP 服务器。随着代码量增加，本地启动常常需要几十秒，修改一行代码的热更新（HMR）也愈发迟钝。

Vite 颠覆了这种模式。在开发模式下，Vite 先直接启动极速的本地 HTTP 服务器；当浏览器发起网页请求并遇到 <script type="module"> 时，浏览器自身负责按需请求当前的 JavaScript 模块。Vite 服务端仅在浏览器索取特定文件时，利用底层高性能的 esbuild 编译器即时完成单文件转换并下发给浏览器。这意味着，无论项目之后扩展到十个页面还是一百个页面，本地开发服务的冷启动时间都基本保持在毫秒级别。

三、执行创建命令与交互选项全流程

Vite 提供了官方脚手架模板生成器 create-vite。在终端中切换到你希望存放项目的目录（例如 Desktop 或自定义的开发目录），然后执行初始化命令。

npm create vite@latest

执行该命令后，脚手架会通过一系列终端交互式提问引导你完成配置。下面是各个步骤的详细选择指南：

1. Project name（项目名称）

终端会提示输入项目名称：

这里直接键入 my-vue-app 并按回车。这个名称将作为新建项目文件夹的名字，同时也会写入项目 package.json 的 name 字段。建议使用小写字母、数字和连字符，不要包含空格或中文字符。

2. Select a framework（选择前端框架）

脚手架支持多种前端框架，终端会出现方向键选择列表：

使用键盘上的方向下键 ↓ 移动高亮光标至 Vue，然后按下回车。

3. Select a variant（选择开发语言与变体）

选定 Vue 后，终端会继续提示选择变体：

新手入门建议先选择 JavaScript 选项。这样生成的工程结构最纯粹、配置最精简，便于初学者集中精力掌握 Vue 3 的核心语法和单文件组件结构，无需一开始就面对 TypeScript 静态类型检查的复杂度。

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

四、剖析生成的工程目录与挂载机制

交互选择完成后，脚手架便会在当前路径下创建 my-vue-app 文件夹。使用 VS Code 或其它代码编辑器打开该目录，我们会看到一个清晰的标准前端工程骨架：

理解这些初始文件的职责分工，能让你在后续添加功能时不迷失方向：

项目的挂载链路非常清晰：浏览器打开根目录下的 index.html，执行其内部声明的 <script type="module" src="/src/main.js"></script>；接着 main.js 引入 App.vue 根组件，并将其渲染挂载到 <div id="app"></div> 容器中。

五、安装依赖与启动本地开发服务器

脚手架只负责生成项目模板代码，并没有自带体积庞大的依赖包。因此在首次运行前，必须通过终端进入项目根目录并安装依赖。

cd my-vue-app
npm install

npm 会读取 package.json 中的 dependencies（如 vue）和 devDependencies（如 vite 和 @vitejs/plugin-vue），并将它们下载存放到新生成的 node_modules 目录中。

安装完成后，执行开发启动脚本：

npm run dev

终端输出提示开发服务器已在 http://localhost:5173/ 就绪。按住键盘上的 Ctrl 键（macOS 上为 Cmd 键）点击终端链接，或者在浏览器地址栏手动输入该地址，即可看到包含 Vite 和 Vue 标志的官方初始欢迎页面。此时，你的第一个 Vue 3 工程已经成功跑起来了！

六、实战上手：编写你的第一个 Vue 响应式组件

为了验证开发体验，我们现在把 src/App.vue 替换为一段清晰、基础的 Vue 3 响应式计数器代码，体验著名的组合式 API（Composition API）与 <script setup> 语法。

在编辑器中打开 src/App.vue，将其全部内容清空，替换为以下代码：

<script setup>
import { ref } from 'vue'

// 声明一个响应式数字变量，初始值为 0
const count = ref(0)

// 递增计数的处理函数
function increment() {
  count.value++
}

// 重置计数的处理函数
function reset() {
  count.value = 0
}
</script>

<template>
  <main class="counter-container">
    <h1>你好，Vue 3 + Vite！</h1>
    <p class="desc">这是我使用 Vite 搭建的第一个 Vue 项目。</p>

    <div class="card">
      <div class="display">
        当前计数值：<span class="number">{{ count }}</span>
      </div>
      <div class="buttons">
        <button @click="increment" class="btn primary">点我 + 1</button>
        <button @click="reset" class="btn secondary">重置归零</button>
      </div>
    </div>
  </main>
</template>

<style scoped>
.counter-container {
  max-width: 500px;
  margin: 60px auto;
  text-align: center;
  font-family: sans-serif;
}
h1 {
  color: #45627E;
  margin-bottom: 8px;
}
.desc {
  color: #5D7184;
  margin-bottom: 24px;
}
.card {
  background: #F3F6FA;
  padding: 32px 24px;
  border-radius: 12px;
  border: 1px solid #D6E1EB;
}
.display {
  font-size: 18px;
  color: #21303E;
  margin-bottom: 20px;
}
.number {
  font-size: 28px;
  font-weight: bold;
  color: #71A397;
  margin-left: 6px;
}
.buttons {
  display: flex;
  gap: 12px;
  justify-content: center;
}
.btn {
  padding: 10px 20px;
  border: none;
  border-radius: 6px;
  font-size: 15px;
  font-weight: 600;
  cursor: pointer;
  transition: opacity 0.2s;
}
.btn:hover {
  opacity: 0.85;
}
.primary {
  background-color: #6B88A6;
  color: #ffffff;
}
.secondary {
  background-color: #E2E8F0;
  color: #475569;
}
</style>

七、新手常见疑问与排错指南

初次使用 Vite 和 Vue 搭建项目时，遇到小问题在所难免。以下整理了新手最常遇到的典型场景及解决办法：

1. 端口被占用，本地地址变成 5174 或 5175？

Vite 默认端口为 5173。如果你同时在另一个终端运行了其他 Vite 实例，或者端口被其它进程占用，Vite 会自动递增尝试下一个可用端口（如 5174），并在终端给出明确提示。这属于正常行为，直接访问终端输出的具体地址即可。若要固定端口，可在 vite.config.js 中配置 server: { port: 3000, strictPort: true }。

2. 如何让局域网内其他设备（如手机）访问开发页面？

默认情况下，开发服务器仅监听 localhost（本机回环地址）。如果希望在手机或同事电脑上预览，可以在运行命令时添加 --host 参数：

npm run dev -- --host

终端会额外输出诸如 Network: http://192.168.1.5:5173/ 的网络地址，同一局域网下的手机浏览器输入该地址即可测试移动端适配。

3. 执行 npm install 速度缓慢或卡住？

这通常是由于网络连接 npm 官方源较慢引起的。可以临时配置国内官方镜像源加速下载：

npm config set registry https://registry.npmmirror.com

配置后再重新执行 npm install 即可明显改善下载速度。

八、生产打包与项目全流程总结

当业务功能开发完毕后，不能把开发服务器直接部署到生产环境。我们需要使用 Vite 内置的打包构建流程，将源码编译为纯静态的 HTML、CSS 和 JavaScript 文件。

npm run build
npm run preview

执行 npm run build 后，Vite 会在后台调用成熟稳定的 Rollup 引擎，对整个项目进行深度的死代码剔除（Tree-shaking）、语法降级转换、代码分包以及体积压缩，最终在根目录下生成一个 dist 文件夹。

而 npm run preview 命令则会在本地模拟启动一个轻量静态资源服务器，直接托管 dist 目录中的构建产物，让你在真正上传服务器前，能百分之百确定打包后的页面功能完全正常。最后，你只需将 dist 目录下的所有文件上传至任何标准的静态 Web 服务器（如 Nginx、Apache、GitHub Pages 或各种云托管 CDN），即可完成正式上线发布。