Vue 3 项目搭建完整流程（Windows 版 · 避坑指南）

目录

前言：前置检查与准备

[1. 确认已通过 nvm-windows 安装 Node.js（推荐）](#1. 确认已通过 nvm-windows 安装 Node.js（推荐）)

[2. 确认 PowerShell 执行策略已设置（避免脚本被禁）](#2. 确认 PowerShell 执行策略已设置（避免脚本被禁）)

[3. 安装 pnpm（Vue 官方推荐包管理器）](#3. 安装 pnpm（Vue 官方推荐包管理器）)

[4. 验证环境](#4. 验证环境)

[第 1 步：创建 Vue 3 项目](#第 1 步：创建 Vue 3 项目)

[Vue 3 项目创建功能选项详解](#Vue 3 项目创建功能选项详解)

试验特性选项说明

选项详解

[第 2 步：安装项目依赖（关键！）](#第 2 步：安装项目依赖（关键！）)

[第 3 步：启动开发服务器](#第 3 步：启动开发服务器)

常见问题速查表

项目结构简览

[Vue 3 项目标准结构详解（Vite + Router + Pinia）](#Vue 3 项目标准结构详解（Vite + Router + Pinia）)

[总结：四步搞定 Vue 3 项目](#总结：四步搞定 Vue 3 项目)

---

前言：前置检查与准备

1. 确认已通过 nvm-windows 安装 Node.js（推荐）

nvm list

✅ 应看到至少一个 Node.js ≥ v20.19.0 的版本（如 20.19.6 或 22.12.0）

2. 确认 PowerShell 执行策略已设置（避免脚本被禁）

以 管理员身份 打开 PowerShell，运行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

输入 Y 确认。

💡 验证：Get-ExecutionPolicy -Scope CurrentUser → 应返回 RemoteSigned

3. 安装 pnpm（Vue 官方推荐包管理器）

npm install -g pnpm

4. 验证环境

---

第 1 步：创建 Vue 3 项目

在你的代码目录（如 E:\code\html）下执行：

cd E:\code\html
pnpm create vue@latest  vue3-app-test

按提示选择：

下面是一个 清晰的功能表格，详细介绍每个选项的作用、是否推荐启用，以及适用场景：

Vue 3 项目创建功能选项详解

序号	选项名称	作用说明	推荐选择	适合人群	补充说明
1	Add TypeScript? （添加 TypeScript？）	使用 TypeScript 编写组件和逻辑，提供类型检查和智能提示	⚠️ 初学者：No 进阶/团队：Yes	- 初学者可先学 JS 版 Vue - 中大型项目强烈建议用 TS	启用后文件扩展名为 .ts / .vue 中 <script setup lang="ts">
2	Add JSX Support? （添加 JSX 支持？）	允许在 Vue 组件中使用 JSX 语法（类似 React）	❌ No（除非有特殊需求）	少数需要动态渲染或混合 JSX 的开发者	普通 Vue 开发几乎用不到
3	Add Vue Router for Single Page Application development? （添加 Vue Router？）	实现多页面 SPA 路由跳转（如 /home → /about）	✅ Yes	几乎所有真实项目都需要	自动生成 router/index.js 和 views/ 目录
4	Add Pinia for state management? （添加 Pinia 状态管理？）	全局状态管理（替代 Vuex），用于跨组件共享数据	✅ Yes	中小型以上项目必备	Vue 官方推荐的状态库，比 Vuex 更简洁
5	Add Vitest for Unit Testing? （添加 Vitest 单元测试？）	基于 Vite 的单元测试框架	⚠️ 学习阶段：No 企业项目：Yes	有测试需求或 TDD 开发者	需额外学习测试编写
6	Add an End-to-End Testing Solution? （添加端到端测试？）	如 Cypress 或 Playwright，模拟用户操作测试整个应用	❌ No（初学可跳过）	QA 自动化或高可靠性项目	配置较复杂，本地运行较慢
7	Add ESLint for code quality? （添加 ESLint？）	代码质量检查，避免低级错误和风格不一致	✅ Yes	所有人	与 VS Code 插件配合，实时提示问题
8	Add Prettier for code formatting? （添加 Prettier？）	自动格式化代码（缩进、引号、分号等）	✅ Yes	所有人	通常与 ESLint 配合使用，保持团队代码风格统一

本文选择以下功能选项

⏱️ 此步骤仅生成项目文件，不会自动安装依赖！

然后回车

试验特性选项说明

选项	说明	是否推荐选择	原因
✅ Oxlint	一个用 Rust 编写的超快 JavaScript/TypeScript linter（类似 ESLint，但速度极快） • 目前处于早期集成阶段 • 可与 ESLint 共存或未来替代	✅ 可以选（推荐尝试）	- 对项目无破坏性 - 仅作为额外 lint 工具，不影响主流程 - 速度快，适合大型项目 - 即使现在不用，了解新技术也有好处
⚠️ rolldown-vite	基于 Rust 的 Rollup 替代品（由 Vite 团队开发），目标是未来替代 Vite 内部的 Rollup • 目前处于非常早期的试验阶段 • 功能不完整，可能无法构建成功	❌ 不要选	- 极不稳定 - 可能导致 vite build 失败 - 仅适合 Vite 核心贡献者测试

然后回车

选项详解

选择	结果	适合人群
Yes	项目中不包含任何示例组件或演示代码 • App.vue 是空的或极简 • views/、components/ 目录可能为空 • 路由和状态管理（如果启用了 Router/Pinia）只有基础配置，无示例逻辑	- 已熟悉 Vue，想从零开始 - 喜欢干净项目结构 - 用于生产项目初始化
No （默认，高亮为 > No）	项目包含官方提供的示例代码 • App.vue 有欢迎界面、导航链接 • HomeView.vue / AboutView.vue 示例页面 • Pinia store 有计数器 demo • 展示如何使用 Composition API、Router Link、响应式等	- 初学者强烈推荐！ - 快速了解项目结构和用法 - 可直接运行查看效果

这样就创建好了一个项目。然后使用Vs Code打开。

第 2 步：安装项目依赖（关键！）

点击终端

执行命令并安装依赖：

pnpm install

✅ 这一步会：

• 下载 vite、vue、vue-router、pinia 等所有依赖
• 生成 node_modules 文件夹
• 创建 pnpm-lock.yaml 锁定版本
  ⚠️ 如果跳过此步，运行 pnpm run dev 会报错：
  'vite' 不是内部或外部命令

显示这样就说明，依赖安装成功！

---

第 3 步：启动开发服务器

pnpm run dev

✅ 成功输出示例：

打开浏览器访问 http://localhost:5173，看到 Vue 欢迎页即成功！

---

常见问题速查表

问题现象	原因	解决方案
pnpm : 无法加载文件 ... 禁止运行脚本	PowerShell 执行策略为 Restricted	以管理员身份运行： Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
'vite' 不是内部或外部命令	未运行 pnpm install	执行 pnpm install 安装依赖
Unsupported engine: wanted node >=20.19.0	Node.js 版本过低	用 nvm 升级到 20.20.0 或 22.12.0+
启动后页面空白/报错	依赖损坏或缓存问题	删除 node_modules 和 pnpm-lock.yaml，重新 pnpm install

---

项目结构简览

Vue 3 项目标准结构详解（Vite + Router + Pinia）

路径	类型	说明	是否可修改	备注
/	根目录	项目根目录	✅	包含配置文件和依赖声明
package.json	文件	项目元信息、依赖列表、脚本命令（如 dev, build）	✅	核心文件，不要随意删除依赖
pnpm-lock.yaml	文件	锁定依赖版本，确保团队安装一致	⚠️ 自动生成	不要手动编辑
vite.config.js	文件	Vite 构建工具配置（别名、插件、代理等）	✅	可扩展（如添加 mock、proxy）
eslint.config.js	文件	ESLint 代码检查规则配置	✅	可自定义规则或关闭某些警告
prettier.config.js	文件	Prettier 代码格式化规则	✅	控制缩进、引号、分号等风格
.gitignore	文件	Git 忽略文件列表	✅	默认已忽略 node_modules/、dist/ 等
/public	目录	静态资源目录（直接复制到根路径）	✅	放 favicon.ico、robots.txt、图片等
public/favicon.ico	文件	浏览器标签图标	✅	可替换为你自己的图标
/src	目录	源代码主目录	✅	所有开发代码放这里
src/main.js	文件	应用入口文件：创建 Vue 实例并挂载	✅	初始化 Router、Pinia、App
src/App.vue	文件	根组件：包含全局布局和 <RouterView />	✅	页面内容在此容器中切换
/src/assets	目录	静态资源（需经构建处理）	✅	放 logo.png、样式变量等，通过 import 引用
/src/components	目录	可复用的 UI 组件	✅	如 Button.vue、Header.vue
/src/views	目录	页面级组件（与路由一一对应）	✅	如 HomeView.vue、AboutView.vue
/src/router	目录	路由配置	✅	通常只有 index.js
src/router/index.js	文件	定义路由表（路径 → 组件映射）	✅	使用 createRouter 创建路由实例
/src/stores	目录	Pinia 状态管理模块	✅	每个 store 一个文件
src/stores/counter.js	文件	示例 store（如果未跳过示例代码）	✅	可删除或替换为业务 store
/tests（可选）	目录	测试文件（如果启用了 Vitest）	✅	否则不存在
/dist（构建后生成）	目录	生产构建输出目录	❌ 自动生成	运行 pnpm run build 后出现，不要提交到 Git

---

总结：四步搞定 Vue 3 项目

1. 升级 Node.js 到 ≥20.19.0（用 nvm）
2. 设置 PowerShell 策略 为 RemoteSigned
3. 创建项目 ：pnpm create vue@latest
4. 安装依赖 ：pnpm install → 再运行 pnpm run dev

只要按顺序操作，99% 的环境问题都能避免！