一份超级详细的 Vue3 + Vite 项目搭建教程，涵盖从环境准备、项目创建到基础配置、功能开发的全流程

一份超级详细的 Vue3 + Vite 项目搭建教程，涵盖从环境准备、项目创建到基础配置、功能开发的全流程。下面我会分步骤拆解，确保你能从零开始搭建一个规范的 Vue3 项目。

一、环境准备

Vue3 + Vite 项目依赖 Node.js 环境，需先完成基础环境配置：

1. 安装 Node.js

• 下载地址：Node.js 官网（推荐 LTS 长期支持版，如 v18/v20）

• 版本要求：Node.js ≥ 14.18.0 或 ≥ 16.0.0（Vite 官方要求）

• **验证安装：**安装完成后，打开终端 / 命令提示符，输入以下命令检查版本：

  node -v  # 输出Node.js版本，如v18.18.0
  npm -v   # 输出npm版本，如v9.8.1
  

2. 选择包管理器（可选）

Vite 支持 npm、yarn、pnpm，推荐使用pnpm（速度更快、磁盘占用更少）：

• 安装 pnpm（若用 npm 可跳过）：

  npm install -g pnpm
  

• 验证 pnpm：

  pnpm -v  # 输出pnpm版本，如v8.15.0
  

二、创建 Vue3 + Vite 项目

使用 Vite 官方脚手架create-vite快速创建项目，步骤如下：

1. 执行创建命令

打开终端，进入目标目录（如cd ~/projects），执行：

# npm
npm create vite@latest

# yarn
yarn create vite

# pnpm（推荐）
pnpm create vite

2. 交互式配置项目

命令执行后，会进入交互式配置流程，按提示输入：

1. Project name：项目名称（如vue3-vite-demo）
2. Select a framework：选择框架 → 选Vue
3. Select a variant：选择变体 → 选JavaScript（或TypeScript，本文用 JS 示例）

3. 进入项目并安装依赖

# 进入项目目录
cd vue3-vite-demo

# 安装依赖（根据包管理器选择）
npm install      # npm
yarn install     # yarn
pnpm install     # pnpm

4. 启动开发服务器

# npm
npm run dev

# yarn
yarn dev

# pnpm
pnpm dev

启动成功后，终端会显示访问地址（如http://127.0.0.1:5173/），打开浏览器访问即可看到 Vue3 默认页面。

三、项目结构解析

创建完成后，项目目录结构如下（重点文件标注）：

vue3-vite-demo/
├── node_modules/       # 项目依赖（自动生成）
├── public/             # 静态资源目录（不会被Vite处理，直接复制到打包目录）
│   └── favicon.ico     # 网站图标
├── src/                # 源代码目录（核心开发目录）
│   ├── assets/         # 静态资源（会被Vite处理，如图片、样式）
│   │   └── vue.svg     # Vue图标
│   ├── components/     # 组件目录（存放自定义组件）
│   │   └── HelloWorld.vue  # 示例组件
│   ├── App.vue         # 根组件（应用入口组件）
│   ├── main.js         # 入口文件（创建Vue实例、挂载应用）
│   └── style.css       # 全局样式
├── .gitignore          # Git忽略文件配置
├── index.html          # 入口HTML（Vite的特殊处理，作为应用入口）
├── package.json        # 项目配置（依赖、脚本命令）
├── vite.config.js      # Vite核心配置文件（端口、代理、插件等）
└── README.md           # 项目说明文档

关键文件详解：

1. index.html：Vite 以 HTML 为入口，而非传统的 JS 入口。文件中通过<script type="module" src="/src/main.js"></script>引入 Vue 入口文件，Vite 会解析此脚本并构建依赖图。

2. src/main.js：Vue3 的入口文件，使用createApp创建应用实例，挂载到#app节点：

   import { createApp } from 'vue'
   import './style.css'
   import App from './App.vue'
   
   createApp(App).mount('#app')
   

3. src/App.vue：根组件，采用 Vue3 的单文件组件（SFC）格式，包含<template>（结构）、<script>（逻辑）、<style>（样式）三部分。

4. vite.config.js：Vite 的配置文件，默认导出一个对象，可配置项目的端口、代理、插件等。

四、基础配置优化

默认项目配置满足基础开发，但实际项目中需优化配置（如别名、代理、端口等）。

1. 配置 Vite（vite.config.js）

修改vite.config.js，添加常用配置：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'  // Node.js路径模块（需Node.js环境）

// https://vitejs.dev/config/
export default defineConfig({
  // 插件配置
  plugins: [vue()],
  
  // 开发服务器配置
  server: {
    port: 3000,         // 自定义端口（默认5173）
    open: true,         // 启动后自动打开浏览器
    host: '0.0.0.0',    // 允许局域网访问（手机/其他电脑可访问）
    proxy: {            // 接口代理（解决跨域）
      '/api': {
        target: 'http://localhost:8080',  // 后端接口地址
        changeOrigin: true,               // 开启跨域
        rewrite: (path) => path.replace(/^\/api/, '')  // 去掉/api前缀
      }
    }
  },
  
  // 路径别名配置（简化import路径）
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')  // @指向src目录
    }
  },
  
  // 构建配置（生产打包）
  build: {
    outDir: 'dist',     // 打包输出目录（默认dist）
    assetsDir: 'assets' // 静态资源存放目录（默认assets）
  }
})

注意：若使用 Node.js 的path模块，需确保项目中安装了@types/node（TypeScript 项目），或直接使用（JS 项目无需额外安装）。

2. 配置 ESLint（代码规范，可选但推荐）

ESLint 用于检查代码规范，Vue3 项目推荐配置：

• 安装依赖：

  pnpm install eslint eslint-plugin-vue @vue/eslint-config-standard eslint-plugin-import eslint-plugin-n eslint-plugin-promise --save-dev
  

• 创建 ESLint 配置文件（.eslintrc.js）：

  module.exports = {
    env: {
      browser: true,
      es2021: true,
      node: true
    },
    extends: [
      'plugin:vue/vue3-essential',  // Vue3基础规则
      'standard'                    // Standard规范
    ],
    parserOptions: {
      ecmaVersion: 'latest'
    },
    plugins: [
      'vue'
    ],
    rules: {
      // 自定义规则（如关闭console警告）
      'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
      'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off'
    }
  }
  

• 添加 ESLint 忽略文件（.eslintignore）：

  node_modules/
  dist/
  *.config.js
  

• 在package.json中添加脚本：

  "scripts": {
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs --fix --ignore-path .eslintignore"
  }
  

• 运行 ESLint 检查：

  pnpm run lint
  

3. 配置 Vue Router（路由，必选）

Vue Router 是 Vue3 的官方路由库，用于页面跳转：

• 安装 Vue Router：

  pnpm install vue-router@4
  

• 创建路由配置文件

  （src/router/index.js）：

  import { createRouter, createWebHistory } from 'vue-router'
  import Home from '@/views/Home.vue'  // 后续创建Home组件
  import About from '@/views/About.vue'// 后续创建About组件
  
  // 路由规则
  const routes = [
    {
      path: '/',
      name: 'Home',
      component: Home
    },
    {
      path: '/about',
      name: 'About',
      component: About
    }
  ]
  
  // 创建路由实例
  const router = createRouter({
    history: createWebHistory(import.meta.env.BASE_URL),  // history模式（需后端配置）
    routes
  })
  
  export default router
  

• 创建视图组件：

  • src/views/Home.vue：

    <template>
      <div class="home">
        <h1>首页</h1>
        <p>这是Vue3 + Vite的首页</p>
      </div>
    </template>
    

  • src/views/About.vue：

    <template>
      <div class="about">
        <h1>关于页</h1>
        <p>这是Vue3 + Vite的关于页</p>
      </div>
    </template>
    

• 在main.js中注册路由：

  import { createApp } from 'vue'
  import './style.css'
  import App from './App.vue'
  import router from './router'  // 引入路由
  
  createApp(App)
    .use(router)  // 注册路由
    .mount('#app')
  

• 修改App.vue，添加路由出口和导航：

  <template>
    <div id="app">
      <!-- 导航栏 -->
      <nav>
        <router-link to="/">首页</router-link> |
        <router-link to="/about">关于</router-link>
      </nav>
      <!-- 路由出口（页面渲染位置） -->
      <router-view />
    </div>
  </template>
  
  <style scoped>
  nav {
    padding: 20px;
    background: #f5f5f5;
    margin-bottom: 20px;
  }
  nav a {
    margin-right: 10px;
    text-decoration: none;
    color: #409eff;
  }
  nav a.router-link-active {
    color: #1e40af;
    font-weight: bold;
  }
  </style>
  

4. 配置 Pinia（状态管理，推荐）

Pinia 是 Vue3 的官方状态管理库（替代 Vuex），用于管理全局状态：

• 安装 Pinia：

  pnpm install pinia
  

• 创建 Pinia 实例并注册（main.js）：

  import { createApp } from 'vue'
  import './style.css'
  import App from './App.vue'
  import router from './router'
  import { createPinia } from 'pinia'  // 引入Pinia
  
  const app = createApp(App)
  app.use(router)
  app.use(createPinia())  // 注册Pinia
  app.mount('#app')
  

• 创建 Store（src/stores/counter.js）：

  import { defineStore } from 'pinia'
  
  // 定义Store（id必须唯一）
  export const useCounterStore = defineStore('counter', {
    // 状态（类似Vuex的state）
    state: () => ({
      count: 0
    }),
    // 计算属性（类似Vuex的getters）
    getters: {
      doubleCount: (state) => state.count * 2
    },
    // 方法（类似Vuex的actions，支持同步/异步）
    actions: {
      increment() {
        this.count++
      },
      decrement() {
        this.count--
      }
    }
  })
  

• 在组件中使用 Store（修改Home.vue）：

  <template>
    <div class="home">
      <h1>首页</h1>
      <p>计数：{{ counterStore.count }}</p>
      <p>双倍计数：{{ counterStore.doubleCount }}</p>
      <button @click="counterStore.increment">+1</button>
      <button @click="counterStore.decrement">-1</button>
    </div>
  </template>
  
  <script setup>
  import { useCounterStore } from '@/stores/counter'
  
  // 创建Store实例
  const counterStore = useCounterStore()
  </script>
  

五、开发基础功能

1. 创建自定义组件

以src/components/HelloButton.vue为例：

<template>
  <button class="hello-btn" :style="{ backgroundColor: color }" @click="handleClick">
    {{ label }}
  </button>
</template>

<script setup>
// 接收父组件传参
defineProps({
  label: {
    type: String,
    default: '按钮'
  },
  color: {
    type: String,
    default: '#409eff'
  }
})

// 向父组件触发事件
const emit = defineEmits(['click'])

const handleClick = () => {
  emit('click')
}
</script>

<style scoped>
.hello-btn {
  border: none;
  padding: 8px 16px;
  color: white;
  border-radius: 4px;
  cursor: pointer;
}
</style>

在Home.vue中使用：

<template>
  <!-- 其他内容 -->
  <HelloButton label="自定义按钮" color="#67c23a" @click="handleBtnClick" />
</template>

<script setup>
// 其他代码
import HelloButton from '@/components/HelloButton.vue'

const handleBtnClick = () => {
  alert('自定义按钮被点击！')
}
</script>

2. 接口请求（Axios）

实际项目中需请求后端接口，使用 Axios：

• 安装 Axios：

  pnpm install axios
  

• 封装 Axios（src/utils/request.js）：

  import axios from 'axios'
  
  // 创建Axios实例
  const service = axios.create({
    baseURL: import.meta.env.VITE_API_BASE_URL,  // 从环境变量读取接口前缀
    timeout: 5000  // 请求超时时间
  })
  
  // 请求拦截器（添加token等）
  service.interceptors.request.use(
    (config) => {
      // 示例：添加token到请求头
      const token = localStorage.getItem('token')
      if (token) {
        config.headers.Authorization = `Bearer ${token}`
      }
      return config
    },
    (error) => {
      return Promise.reject(error)
    }
  )
  
  // 响应拦截器（统一处理错误）
  service.interceptors.response.use(
    (response) => {
      const res = response.data
      // 示例：统一处理业务错误
      if (res.code !== 200) {
        alert(res.message || '请求失败')
        return Promise.reject(res)
      }
      return res
    },
    (error) => {
      alert(error.message || '服务器错误')
      return Promise.reject(error)
    }
  )
  
  export default service
  

• 创建环境变量文件（.env.development，开发环境）：

  VITE_API_BASE_URL = /api  # 对应vite.config.js中的代理前缀
  

• 创建 API 请求文件（src/api/user.js）：

  import request from '@/utils/request'
  
  // 获取用户列表
  export const getUserList = () => {
    return request({
      url: '/user/list',
      method: 'get'
    })
  }
  

• 在组件中使用（About.vue）：

  <template>
    <div class="about">
      <h1>关于页</h1>
      <button @click="getUsers">获取用户列表</button>
      <div v-if="userList.length">
        <h3>用户列表</h3>
        <ul>
          <li v-for="user in userList" :key="user.id">{{ user.name }}</li>
        </ul>
      </div>
    </div>
  </template>
  
  <script setup>
  import { ref } from 'vue'
  import { getUserList } from '@/api/user'
  
  const userList = ref([])
  
  const getUsers = async () => {
    try {
      const res = await getUserList()
      userList.value = res.data
    } catch (err) {
      console.error(err)
    }
  }
  </script>
  

六、项目运行与打包

1. 开发环境运行

pnpm run dev

访问http://localhost:3000（自定义端口），即可看到带路由、状态管理的完整项目。

2. 生产环境打包

pnpm run build

打包完成后，生成dist目录，包含静态 HTML、JS、CSS 文件。

3. 预览打包结果

pnpm run preview

Vite 会启动一个本地服务器，预览打包后的生产环境效果。

七、常见问题与优化

1. 路由模式（history）的后端配置

若使用createWebHistory（history 模式），需后端配置支持刷新（否则刷新页面会 404）：

• Nginx 配置：

  location / {
    try_files $uri $uri/ /index.html;
  }
  

2. 静态资源处理

• public目录下的资源：直接通过/文件名访问（如/favicon.ico）；
• src/assets目录下的资源：通过import或@/assets/文件名访问（如<img src="@/assets/vue.svg" />）。

3. 环境变量使用

Vite 中环境变量需以VITE_开头，通过import.meta.env.VITE_XXX访问（如import.meta.env.VITE_API_BASE_URL）。

总结

1. 环境准备：安装 Node.js（≥14.18），可选 pnpm 提升效率；
2. 项目创建：用create-vite选择 Vue3 模板，快速生成项目；
3. 核心配置：优化vite.config.js（端口、代理、别名），集成 Vue Router（路由）、Pinia（状态管理）；
4. 开发规范：配置 ESLint 保证代码质量，封装 Axios 处理接口请求；
5. 打包部署：pnpm run build打包，后端配置 history 模式支持刷新。

通过以上步骤，你已搭建出一个结构规范、功能完整的 Vue3 + Vite 项目，可直接用于实际开发！