要点
Vue 3 的官方工具链一句话说清：Vite 负责开发服务器与构建，create-vue 负责生成工程骨架，VS Code 的 Vue (Official) 扩展负责语言支持，Vue DevTools 负责调试。三种起步方式（CDN、最小工程、全家桶）按使用场景选，不按”越全越好”选。
系统要求
工具链的地基是 Node.js。Vite 6 要求 Node 18/20/22，低于它会在安装或启动时报错；新装建议直接用 22 的 LTS。操作系统不限，浏览器用当前版 Chrome 或 Firefox 即可。先验证：
node --version # 需要 v18/20/22，建议 22 LTS
npm --version不满足就升级：Windows 用 winget install OpenJS.NodeJS.LTS，macOS 用 brew install node@22；多项目共存不同 Node 版本时用 nvm（Windows 用 nvm-windows），装完重开终端再验证一次。
三种起步方式与选择依据
网上教程开篇各异，先把三条路摆清楚。判断依据只有一条：你要的是一页演示，还是一个工程。
| 方式 | 得到什么 | 适合 | 另外两个场景为什么不用它 |
|---|---|---|---|
| CDN（script 标签） | 一个 HTML 页面 + 全局 Vue 对象 | 学语法、给既有页面加交互 | 没有单文件组件（SFC）与构建步骤，模板在浏览器里运行时编译；正式工程不这么写 |
| create-vue 最小工程 | Vite 工程、package.json 与锁文件 | 单页应用起步、小工具 | 路由、状态管理、测试都要后续自己加，多页面应用会补得很零碎 |
| create-vue 全家桶 | 以上 + Router + Pinia + Vitest 等 | 明确要做多页面应用 | 第一周学语法时背不动这套目录——演示 ref 响应式用不上路由和状态库 |
CDN 方式长这样，能跑，但只当练习场：
<div id="app">{{ count }}</div>
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
<script>
const { createApp, ref } = Vue
createApp({
setup() {
return { count: ref(0) } // 改 count.value，页面自动变
}
}).mount('#app')
</script>后两条路从同一条命令进入，差别只在交互时勾了多少选项。
创建工程
create-vue 是官方脚手架，构建职责全部交给 Vite；它只在创建那一刻工作，之后不再介入项目：
npm create vue@latest my-first-vue
1. 包管理器任选：pnpm create vue@latest / yarn create vue / bun create vue
cd my-first-vue
npm install
npm run dev交互提示逐项问：TypeScript、JSX 支持、Vue Router（单页应用路由）、Pinia（状态管理）、Vitest（单元测试）、端到端测试、ESLint 与 Prettier。第一遍学语法建议只选 ESLint，其余全否——少一层目录少一层干扰。事后要补某一项，按 Vue 官方文档”向现有工程添加能力”一节的步骤装，不必重建工程。
npm run dev 启动 Vite 开发服务器，默认地址 http://localhost:5173；保存代码即热更新（HMR，Hot Module Replacement），只替换改动模块，不整页刷新。当前 Vite 主线是 6.x，打包器仍是 Rollup、转换器仍是 esbuild；官方在推进 Rolldown（Rust 写的打包器）的整合，仍属实验性质、尚未成为默认，日常使用不用关心。
编辑器与调试工具
VS Code 装 Vue (Official) 扩展（市场 ID Vue.volar，即原 Volar），单文件组件的模板补全与类型检查都靠它。勾了 TypeScript 的工程，命令行类型检查用 vue-tsc——它是能读懂 .vue 文件的 tsc 包装器，通常挂在构建脚本里：vue-tsc --noEmit && vite build。
Vue DevTools 有两种形态，按工程入口选：
| 形态 | 怎么装 | 说明 |
|---|---|---|
| Vite 插件（推荐） | npm install -D vite-plugin-vue-devtools 后在 vite.config.js 挂载 |
仅开发环境生效；组件树、响应式状态、路由检查最全 |
| 浏览器扩展 | Chrome/Edge 商店搜 Vue.js devtools | 适合 CDN 页面或非 Vite 工程；7.x 起只支持 Vue 3，Vue 2 应用要用旧版 6.x |
装完 DevTools 插件后，vite.config.js 长这样——Vue 工程的最小配置就这两段，之后加路由、加测试才需要再动它：
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueDevTools from 'vite-plugin-vue-devtools'
export default defineConfig({
plugins: [
vue(), // 让 Vite 认识 .vue 文件，没它一切无从谈起
vueDevTools(), // F12 面板里的组件树与状态检查
],
// server: { proxy: { '/api': 'http://localhost:8080' } } // 需要转发后端时再加
})目录速读
my-first-vue/
├── index.html # 入口页在根目录，不在 public/——Vite 工程的特征
├── vite.config.js # Vite 配置：插件、代理、构建选项
├── package.json # scripts: dev / build / preview
└── src/
├── main.js # 入口：createApp(App).mount('#app')
├── App.vue # 根组件，后续练习都从这里开始
└── components/ # 拆出的子组件与 create-next-app 的显著差异：入口 HTML 在根目录且由你持有，构建产物在 dist/，npm run preview 可本地预览构建结果——发布前务必跑一次，开发模式正常、构建后白屏的问题只有这一步能提前暴露。
日常命令与产物
| 命令 | 作用 | 什么时候用 |
|---|---|---|
npm run dev |
开发服务器，带 HMR | 写代码时全程开着 |
npm run build |
生产构建，产物进 dist/ | 发布前验证一次，顺带跑出部署物 |
npm run preview |
本地起服务器伺服 dist/ | 构建后本地过一遍再上传 |
npm ci |
按锁文件原样重装依赖 | 依赖装坏、换机器、CI 环境 |
pnpm 与 yarn 用户只是把 npm 换成对应命令（pnpm dev / pnpm ci），行为等价。团队协作时统一包管理器比选哪个更重要——锁文件格式不同，混用会导致依赖解析各说各话。
常见问题
Q1: 旧教程让我装 @vue/cli，装吗
不装。Vue CLI 已停在维护状态，Vue 3 的官方起步是 create-vue。分辨特征：让你执行 vue create xxx 或 npm install -g @vue/cli 的教程都是 Vue CLI 时代的；照抄它的 main.js（new Vue()、Vue.use()）在 Vue 3 里跑不起来，Vue 3 的入口是 createApp。
Q2: npm run dev 报 Node 版本错误
node -v 确认版本，Vite 6 需要 Node 18/20/22，新装建议 22。用 nvm 的话先 nvm install 22 再 nvm use 22，重开终端。
Q3: 5173 端口被占
Vite 检测到占用会提示自动换端口，确认即可；也可显式指定 npm run dev -- --port 5174。
Q4: 依赖安装慢或失败
大陆网络环境先换镜像：npm config set registry https://registry.npmmirror.com。装到一半失败时，保留锁文件删 node_modules 重装（npm ci），不要删锁文件——那会把所有依赖版本重新解析一遍。
最佳实践
反模式一：照抄 Vue CLI 时代教程。入口写法、插件注册方式全变了，旧代码混进新工程只会让报错指向不存在的 API。
反模式二：第一次创建就勾满全家桶。学习期的目录噪音远大于收益，Router 和 Pinia 等真正遇到”多页面””跨组件共享状态”再按官方文档加。
创建后立即提交一次 git，包含锁文件。脚手架只是起点，之后的每次依赖变化都应该能从提交历史里解释清楚。
检查清单
- node -v 满足 Vite 6 的要求（18/20/22，建议 22）
- npm create vue@latest 建好工程，选项能说出每一项的作用
- npm run dev 打开 http://localhost:5173 看到欢迎页
- 装好 Vue (Official) 扩展，打开 App.vue 无报错波浪线
- npm run build && npm run preview 各跑通一次
- git 提交了 package.json 与锁文件
下一步
这一篇的产出是一个能启动、能构建、能调试的最小工程，工具链到此够用很久。下一篇《第一个 Vue 3 应用》在这个骨架里写一个待办清单，体会 ref 响应式与模板语法的即时收益；已写过 React 的读者，站内的《Next.js 环境搭建与工具链》与本章同结构，两相对照能看出两个脚手架在入口 HTML、路由约定上的分野，而《用 Next.js 做一个真的能被搜到的内容站》是这些工具用在真实项目里的样子。
版本核实（撰写时检索，2025-03）：Vue 当前稳定线为 3.5.x，3.6（含 Vapor Mode）仍在实验、未发布；Vite 当前主线 6.x，官方在推进 Rolldown 整合、尚未成为默认；官方脚手架为 create-vue（npm create vue@latest），Vue CLI 处于维护状态；Vue DevTools 的 Vite 插件正常可用，浏览器扩展 7.x 起仅支持 Vue 3（Vue 2 用旧版 6.x）。安装命令一律不钉版本号，具体版本以官方文档与你的锁文件为准。