Vue3 安装与配置完全指南

Vue.js 是目前最流行的前端框架之一。本教程将带你从零开始完成 Vue3 的安装与配置。

--- ## 📋 前置条件 在开始安装 Vue3 之前，请确保你的开发环境满足以下要求：

Node.js >= 16.0 已安装

npm >= 7.0 或 pnpm 已安装

已安装 VS Code 或其他代码编辑器

已安装 Git

推荐使用 nvm（Node Version Manager）来管理 Node.js 版本，方便在不同项目之间切换。

### 检查环境 打开终端，运行以下命令检查环境： 
1
2
node -v    # 应输出 v16.0.0 或更高版本
npm -v     # 应输出 7.0.0 或更高版本
--- ## 🚀 创建 Vue3 项目 Vue3 提供了两种创建项目的方式：使用 Vite 创建（推荐）和使用 Vue CLI 创建。 ### 方式一：使用 Vite 创建（推荐）

Vite 是新一代前端构建工具，具有极快的冷启动速度和热模块替换（HMR）能力，是 Vue 官方推荐的构建方式。

1
2
3
4
5
6
7
8
# 使用 npm
npm create vue@latest

# 使用 pnpm（推荐）
pnpm create vue@latest

# 使用 yarn
yarn create vue@latest
运行命令后，会出现交互式配置向导：
查看完整配置选项 
1
2
3
4
5
6
7
8
9
10
✔ Project name: … my-vue-app
✔ Add TypeScript? … No / Yes
✔ Add JSX Support? … No / Yes
✔ Add Vue Router for Single Page Application development? … No / Yes
✔ Add Pinia for state management? … No / Yes
✔ Add Vitest for Unit testing? … No / Yes
✔ Add an End-to-End Testing Solution? … No / Cypress / Playwright
✔ Add ESLint for code quality? … No / Yes
✔ Add Prettier for code formatting? … No / Yes
✔ Add Vue DevTools extension for debugging? … No / Yes

如果是初学者，建议先 不要 勾选 TypeScript 和 JSX Support，保持简单配置即可。后续可以随时添加。

### 方式二：使用 Vue CLI 创建
查看使用 Vue CLI 创建项目 
1
2
3
4
5
# 全局安装 Vue CLI
npm install -g @vue/cli

# 创建项目
vue create my-vue-app

此方式已不推荐，Vue CLI 已进入维护模式

--- ## 📦 安装依赖 项目创建完成后，进入项目目录并安装依赖： 
1
2
cd my-vue-app
npm install

primary

--- ## 🏗️ 项目结构 安装完成后，项目目录结构如下：
查看项目目录结构 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
my-vue-app/
├── public/              # 静态资源（不经过构建处理）
│   └── favicon.ico
├── src/                 # 源代码目录
│   ├── assets/          # 静态资源（经过构建处理）
│   ├── components/      # 公共组件
│   ├── router/          # 路由配置
│   ├── stores/          # Pinia 状态管理
│   ├── views/           # 页面视图
│   ├── App.vue          # 根组件
│   └── main.js          # 入口文件
├── index.html           # HTML 模板
├── package.json         # 项目配置
├── vite.config.js       # Vite 配置文件
└── README.md            # 项目说明
--- ## ⚙️ 核心配置详解 ### 1. Vite 配置文件 Vite 的配置文件为 `vite.config.js`： 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  server: {
    port: 3000,       // 开发服务器端口
    open: true        // 启动时自动打开浏览器
  }
})

配置 @ 别名后，在项目中可以使用 @/components/xxx 代替相对路径，代码更加简洁。

### 2. 路由配置（Vue Router） 如果创建项目时选择了 Vue Router，配置文件位于 `src/router/index.js`： 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '../views/HomeView.vue'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: '/',
      name: 'home',
      component: HomeView
    },
    {
      path: '/about',
      name: 'about',
      // 懒加载方式
      component: () => import('../views/AboutView.vue')
    }
  ]
})

export default router

使用 import() 动态导入实现路由懒加载，可以有效减小首屏加载体积。

### 3. 状态管理（Pinia） Pinia 是 Vuex 的继任者，API 更加简洁： 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// src/stores/counter.js
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0
  }),
  getters: {
    doubleCount: (state) => state.count * 2
  },
  actions: {
    increment() {
      this.count++
    }
  }
})
### 4. 环境变量配置
查看环境变量配置方法

在项目根目录创建以下文件：

1
2
3
4
.env                # 所有环境都会加载
.env.development    # 开发环境
.env.production     # 生产环境
.env.staging        # 预发布环境

环境变量必须以 VITE_ 开头才能在代码中访问：

1
2
3
# .env.development
VITE_API_BASE_URL=http://localhost:3000/api
VITE_APP_TITLE=My Vue App (Dev)
1
2
// 在代码中使用
console.log(import.meta.env.VITE_API_BASE_URL)
--- ## 🎯 编写第一个组件 创建一个简单的 Vue3 组件，体验 Composition API 的强大： 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<!-- src/components/HelloWorld.vue -->
<script setup>
import { ref, computed } from 'vue'

const name = ref('Vue3')
const count = ref(0)

const greeting = computed(() => `Hello, ${name.value}!`)
</script>

<template>
  <div class="hello-world">
    <h1>{{ greeting }}</h1>
    <p>计数器: {{ count }}</p>
    <button @click="count++">点击 +1</button>
  </div>
</template>

<style scoped>
.hello-world {
  text-align: center;
  padding: 2rem;
}
</style>

script setup 是 Vue3.2+ 引入的语法糖，无需手动注册组件和返回变量，代码更加简洁高效。

--- ## 🔧 常用插件配置 ### ESLint + Prettier

ESLint - 代码质量检查

Prettier - 代码格式化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// .eslintrc.cjs
module.exports = {
  root: true,
  env: {
    node: true
  },
  extends: [
    'plugin:vue/vue3-essential',
    'eslint:recommended',
    '@vue/eslint-config-prettier'
  ],
  parserOptions: {
    ecmaVersion: 'latest'
  },
  rules: {
    'no-unused-vars': 'warn',
    'vue/multi-word-component-names': 'off'
  }
}
### 推荐的 VS Code 插件
Volar ESLint Prettier

如果之前安装了 Vetur 插件，请 务必禁用 它，否则会与 Volar 产生冲突！

--- ## 🏃 启动与构建 ### 开发模式 
1
npm run dev

success

启动后访问 http://localhost:3000 即可看到项目页面。 ### 生产构建 
1
2
3
4
5
# 构建生产版本
npm run build

# 预览构建结果
npm run preview

info

--- ## 📊 Vue3 学习路线

primary

success

info

warning

danger

--- ## 🔗 参考资源

Vue3 官方文档

https://cn.vuejs.org/

Vite 官方文档

https://cn.vitejs.dev/

Vue Router

https://router.vuejs.org/zh/

Pinia

https://pinia.vuejs.org/zh/

❓ 常见问题

Q: npm install 速度太慢怎么办？

推荐使用国内镜像源：


1
2
3
4
5
# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

# 或者使用 pnpm（更推荐）
npm install -g pnpm

Q: 端口 3000 被占用怎么办？

修改 vite.config.js 中的端口号：

1
2
3
4
5
export default defineConfig({
  server: {
    port: 8080  // 修改为其他端口
  }
})

或者启动时指定端口：

1
npm run dev -- --port 8080
Q: 如何升级 Vue3 到最新版本？ 
1
2
3
4
5
# 查看当前版本
npm list vue

# 升级到最新版本
npm update vue @vue/compiler-sfc
赠前端开发者

代码如诗行行写，
框架万千任君采。
Vue3新篇开，
前端之路花盛开。

Vue3 渐进式 JavaScript 框架 Vite 极速构建工具 Pinia 状态管理