Vue3 安装与配置完全指南

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

📋 前置条件

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

Node.js >= 16.0
npm >= 7.0（或 pnpm）
Git
VS Code 或其他代码编辑器

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

打开终端，运行以下命令检查环境：

1 2	node -v # 应输出 v16.0.0 或更高版本 npm -v # 应输出 7.0.0 或更高版本

📥 安装 Node.js

方式一：MSI 安装包（推荐）

前往 Node.js 官网下载 LTS（长期支持）版本的 .msi 安装包
双击运行安装包，安装时务必勾选 Add to PATH，其余一路点击 Next 即可
安装完成后打开终端验证：

1 2	node -v # 应输出 v20.x.x 或更高版本 npm -v # 应输出 10.x.x 或更高版本

MSI 安装包会自动配置环境变量，无需手动设置。

方式二：ZIP 压缩包（手动配置环境变量）

前往 Node.js 官网下载 ZIP 压缩包
解压到目标目录，例如 D:\nodejs
在 Node.js 安装目录下新建两个文件夹：node_cache（npm 缓存）和 node_global（全局包安装目录）
配置系统环境变量：

查看环境变量配置步骤

Windows：

右键”此电脑” → 属性 → 高级系统设置 → 环境变量

新建系统变量 NODE_HOME，值为 Node.js 的实际安装路径，例如 D:\nodejs

在 Path 中添加：
- %NODE_HOME%
- %NODE_HOME%\node_cache
- %NODE_HOME%\node_global

验证安装：

1 2	node -v npm -v

修改 npm 全局模块下载路径和缓存路径：

1 2	npm config set prefix "%NODE_HOME%\node_global" npm config set cache "%NODE_HOME%\node_cache"

替换 npm 镜像为淘宝源：

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

全局安装基于淘宝源的 cnpm：

1	npm install -g cnpm --registry=https://registry.npmmirror.com

安装完成后可通过 cnpm -v 验证是否安装成功。之后可以用 cnpm 替代 npm 来安装依赖，速度更快。

使用 ZIP 方式安装时，如果终端重启后 node 命令不可用，请检查环境变量是否配置正确。

🚀 创建 Vue3 项目

使用 Vite 创建 Vue3 项目，这是 Vue 官方推荐的构建方式。

使用 Vite 创建

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

# 使用 npm
npm create vue@latest

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

# 使用 yarn
yarn create vue@latest

运行命令后，会出现交互式配置向导：

查看完整配置选项（含中文翻译）

✔ Project name: … my-vue-app          # 项目名称
✔ Add TypeScript? … No / Yes          # 是否添加 TypeScript 支持
✔ Add JSX Support? … No / Yes         # 是否添加 JSX 支持
✔ Add Vue Router for Single Page Application development? … No / Yes  # 是否添加 Vue Router 单页应用路由
✔ Add Pinia for state management? … No / Yes  # 是否添加 Pinia 状态管理
✔ Add Vitest for Unit testing? … No / Yes     # 是否添加 Vitest 单元测试
✔ Add an End-to-End Testing Solution? … No / Cypress / Playwright  # 是否添加端到端测试方案
✔ Add ESLint for code quality? … No / Yes     # 是否添加 ESLint 代码质量检查
✔ Add Prettier for code formatting? … No / Yes  # 是否添加 Prettier 代码格式化
✔ Add Vue DevTools extension for debugging? … No / Yes  # 是否添加 Vue DevTools 调试扩展

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

📦 安装依赖

项目创建完成后，进入项目目录并安装依赖：

1 2	cd my-vue-app npm install

🏃 启动与构建

开发模式

1	npm run dev

启动后访问 http://localhost:3000 即可看到项目页面。

生产构建

# 构建生产版本
npm run build

# 预览构建结果
npm run preview

🏗️ 项目结构

安装完成后，项目目录结构如下：

查看项目目录结构

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            # 项目说明

🧩 常用插件列表

以下是创建 Vue3 项目时可选的插件，建议根据实际需求按需安装：

插件	介绍	安装命令
TypeScript	JavaScript 的超集，添加静态类型检查，提升代码可维护性和开发体验	`npm install typescript`
JSX Support	在 Vue 中使用 JSX 语法编写组件，适合从 React 迁移或偏好 JSX 的开发者	`npm install @vitejs/plugin-vue-jsx`
Vue Router	Vue 官方路由管理器，用于构建单页应用（SPA）的页面导航	`npm install vue-router`
Pinia	Vue 官方推荐的新一代状态管理库，替代 Vuex，API 更简洁直观	`npm install pinia`
Vitest	基于 Vite 的单元测试框架，配置简单、运行速度快	`npm install -D vitest`
Cypress / Playwright	端到端（E2E）测试框架，用于模拟用户操作进行自动化测试	`npm install -D cypress` 或 `npm install -D @playwright/test`
ESLint	代码质量检查工具，自动检测代码中的潜在问题和不规范写法	`npm install -D eslint`
Prettier	代码格式化工具，统一团队的代码风格（缩进、引号、分号等）	`npm install -D prettier`
Vue DevTools	浏览器调试扩展，支持组件树查看、状态检查、时间线调试等功能	在浏览器扩展商店搜索 “Vue.js devtools” 安装

创建项目时通过 npm create vue@latest 的交互式向导可以直接勾选以上插件，无需手动逐个安装。

⚙️ 核心配置详解

1. Vite 配置文件

Vite 的配置文件为 `vite.config.js`：

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：

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 更加简洁：

// 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. 环境变量配置

查看环境变量配置方法

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

.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)

❓ 常见问题

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

推荐使用国内镜像源：

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

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

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

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

export default defineConfig({
  server: {
    port: 8080  // 修改为其他端口
  }
})

或者启动时指定端口：

1	npm run dev -- --port 8080

Q: 如何升级 Vue3 到最新版本？

# 查看当前版本
npm list vue

# 升级到最新版本
npm update vue @vue/compiler-sfc

Vue3 安装与配置完全指南

📋 前置条件

📥 安装 Node.js

方式一：MSI 安装包（推荐）

方式二：ZIP 压缩包（手动配置环境变量）

🚀 创建 Vue3 项目

使用 Vite 创建

📦 安装依赖

🏃 启动与构建

开发模式

生产构建

🏗️ 项目结构

🧩 常用插件列表

⚙️ 核心配置详解

1. Vite 配置文件

2. 路由配置（Vue Router）

3. 状态管理（Pinia）

4. 环境变量配置

❓ 常见问题

🔗 参考资源