讲解

现代前端项目不再是「一个 HTML 加几个 script 标签」：单文件组件需要编译、ES 模块需要打包、开发时需要热更新。这些工作由构建工具完成。Vue 官方推荐的构建工具是 Vite——它利用浏览器原生 ES 模块能力做按需编译，冷启动通常在一秒以内，保存文件后页面毫秒级热更新，体验和传统打包器（webpack）完全不是一个时代。

搭环境的第一步是安装 Node.js。建议用 LTS 版本（20 或更高），安装后自带 npm 包管理器。验证安装只需两条命令：node -v 和 npm -v。如果公司网络拉包慢，可以把 npm 源切换到国内镜像。

创建 Vue 项目用官方脚手架 create-vue，命令是 npm create vue@latest。它是个交互式向导，会问你项目名、要不要 TypeScript、要不要 Router 和 Pinia、要不要 ESLint 和 Prettier。学习阶段的建议是：TypeScript 可以先不选（本教程示例以 JavaScript 为主），Router 和 Pinia 暂时不选（到对应章节再加，你会更清楚它们解决了什么问题），ESLint 和 Prettier 建议选上，它们能让代码风格自动保持一致。

脚手架生成的目录里，最重要的文件是 src/main.js（应用入口，调用 createApp 挂载根组件）、src/App.vue（根组件）和 vite.config.js（构建配置）。日常开发只需要三条命令：npm install 装依赖、npm run dev 起开发服务器、npm run build 产出生产构建（输出到 dist/ 目录）。

还有一件小事但很重要：装一个顺手的编辑器。VS Code 配合官方扩展 Vue - Official（以前叫 Volar）是事实标准，它提供单文件组件的语法高亮、类型提示和模板内的自动补全。

示例

create-vue 的完整流程（仅示意，版本号以你实际安装为准）：

node -v          # v22.x
npm create vue@latest my-app
cd my-app
npm install
npm run dev      # http://localhost:5173

项目跑起来后，package.json 里的 scripts 和 dependencies 描述了项目的「骨架」。下面这段代码模拟脚手架分析依赖版本的过程——比如判断 Vue 版本是否满足项目要求（在本教程构建时被真实执行）：

import assert from 'node:assert/strict';

const pkg = {
  scripts: { dev: 'vite', build: 'vite build', preview: 'vite preview' },
  dependencies: { vue: '^3.5.13' },
  devDependencies: { vite: '^6.0.5', '@vitejs/plugin-vue': '^5.2.1' },
};

// 语义化版本里 ^3.5.13 表示「兼容 3.x，不低于 3.5.13」
function satisfies(version, range) {
  const [major, minor, patch] = version.split('.').map(Number);
  const [rMajor, rMinor, rPatch] = range.replace('^', '').split('.').map(Number);
  if (major !== rMajor) return false; // ^ 锁死主版本
  if (minor !== rMinor) return minor > rMinor;
  return patch >= rPatch;
}

assert.ok(satisfies('3.5.13', pkg.dependencies.vue));
assert.ok(satisfies('3.6.0', pkg.dependencies.vue));
assert.ok(!satisfies('4.0.0', pkg.dependencies.vue)); // 主版本不符
assert.ok(!satisfies('3.4.0', pkg.dependencies.vue)); // 次版本过低

// 三个核心 script 必须齐全，项目才算脚手架完整
for (const cmd of ['dev', 'build', 'preview']) {
  assert.ok(pkg.scripts[cmd], '缺少 script: ' + cmd);
}

console.log('scripts:', Object.keys(pkg.scripts).join(', '));
console.log('vue 版本范围', pkg.dependencies.vue, '允许 3.6.0，拒绝 4.0.0');

常见坑

  • Node 版本太低：Vite 6 要求 Node 18+，用 node -v 确认；老机器上 14/16 会报各种莫名其妙的错。
  • 把 node_modules 提交进 Git：脚手架生成的 .gitignore 已排除它，别手动加回来；团队成员用 npm install 按 lock 文件还原即可。
  • 全局安装 vite：不要 npm i -g vite，项目依赖里的本地版本才保证团队环境一致，通过 npm run dev 调用。
  • 端口被占用以为项目坏了：dev 服务器默认 5173，被占了会自动换端口，看清终端里的实际地址。
  • 直接在 dist/ 上改代码：dist 是构建产物，改源文件 src/ 后重新 build，产物里的代码是压缩混淆过的。

小结

Node.js（LTS）→ npm create vue@latest → npm install → npm run dev，四步出环境；构建交给 Vite，编辑器用 VS Code + Vue - Official。下一章进入 Vue 3 的心脏：ref 与 reactive。