Vue / 知识点

Vue 3 开发速查手册

手册条目

使用官方脚手架创建新的 Vue 3 项目并选择 TypeScript、路由和状态管理能力。

初始化 Vite 项目

需要创建新的 Vue 3 单页应用,并在脚手架阶段一次启用 TypeScript、Vue Router 和 Pinia 时使用本条目。最终会得到一个基于 Vite、可直接安装依赖并启动的项目目录。

命令定位

在准备存放项目的父目录执行 create-vue。开始前确认 node -v 和 npm -v 能正常输出;若脚手架提示 Node.js 版本不满足要求,先升级 Node.js,再重新创建项目。

bash
node -v
npm -v

预期输出

text
v<NODE_VERSION>
<NPM_VERSION>

版本号因本机环境而异;命令不可用时,说明 Node.js 或 npm 尚未正确安装,或终端的 PATH 未刷新。

高频用法

推荐使用 Vue 官方脚手架的交互模式,项目名示例为 vue-admin-app。依次选择 TypeScript、Vue Router 和 Pinia,其余测试、格式化与调试选项按团队规范决定。

bash
npm create vue@latest

预期输出

text
✔ Project name: … vue-admin-app
✔ Add TypeScript? … Yes
✔ Add JSX Support? … No
✔ Add Vue Router for Single Page Application development? … Yes
✔ Add Pinia for state management? … Yes
...
Scaffolding project in ./vue-admin-app...
Done.

提示项可能随 create-vue 版本调整,但核心读取方式不变:确认项目名正确,并检查 TypeScript、Router、Pinia 三项均选择 Yes。

项目生成后进入目录并安装锁定依赖。首次安装会创建或更新 package-lock.json,后续团队成员应优先使用该锁文件保持版本一致。

bash
cd vue-admin-app
npm install

预期输出

text
added <COUNT> packages, and audited <COUNT> packages in <TIME>
found 0 vulnerabilities

包数量、耗时和审计结果会随版本及网络环境变化。若审计结果不为零,不要直接执行带 --force 的自动修复,应先确认升级是否会引入破坏性变更。

输出与验证

检查脚手架是否真正加入三项能力,而不是只依赖交互记录。以下命令读取 package.json 中的关键依赖;版本号为动态值。

bash
npm pkg get dependencies.vue dependencies.vue-router dependencies.pinia devDependencies.typescript

预期输出

text
{
  "dependencies.vue": "^<VERSION>",
  "dependencies.vue-router": "^<VERSION>",
  "dependencies.pinia": "^<VERSION>",
  "devDependencies.typescript": "~<VERSION>"
}

四个字段都有版本值,表示 Vue、路由、状态管理和 TypeScript 已写入项目配置。某字段返回空值时,通常是创建时未选择对应能力,应重新创建项目,或在确认入口配置后手动补装。

风险与边界

不要在含有重要文件的非空目录中直接使用 . 作为项目名,文件冲突可能导致创建失败或覆盖同名模板文件。安全做法是创建新的独立目录,确认生成结果后再迁移已有代码。

不要混用 npm、pnpm、Yarn 和 Bun 安装同一份依赖,否则多个锁文件可能让本地与 CI 解析出不同版本。项目已经生成 package-lock.json 时,继续使用 npm;切换包管理器前应删除旧锁文件和 node_modules,再统一重新安装。

排障清单

  • 出现 Unsupported engine 或 Node.js 版本提示:升级 Node.js,关闭并重新打开终端后再次检查 node -v。
  • 包下载超时或连接重置:先检查代理、DNS 和 npm registry 配置,不要反复删除项目目录。
  • 目录已存在或文件冲突:换用新的项目名,或先备份并清空目标目录。
  • 安装后缺少 Router 或 Pinia:检查 package.json 与 src/main.ts,确认依赖存在且插件已通过 app.use(...) 注册。

兼容性

使用其他包管理器时,创建命令分别为 pnpm create vue@latest、yarn create vue@latest 或 bun create vue@latest。同一项目只保留一种锁文件,并使用对应的安装与脚本命令。

目录与阅读设置

记录一个想法

Vue 3 开发速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通