create-vue是Vue官方唯一维护的脚手架，推荐执行npx create-vue@latest初始化项目，需Node≥16.12、npm≥9.0，建议启用TypeScript、Vue Router和Pinia，并注意Volar接管模式及vite.config.ts代理配置。
npm create vue@latest 初始化项目最省事
官方已弃用全局 @vue/cli，create-vue 是当前唯一维护的脚手架。直接运行 npx create-vue@latest（比 npm init vue@latest 更稳，避免 npm 版本兼容问题）。
执行前确认：node -v ≥ 16.12（推荐 v20+），否则创建失败；npm -v ≥ 9.0（低版本可能卡在依赖解析）。
- 选
Add TypeScript?→ 强烈建议 Yes：Vue3 的响应式类型（如ref()、defineProps）依赖 TS 推导，后期补写成本高 - 选
Add Vue Router?→ 管理后台或含多视图必须开；纯静态页可跳过 - 选
Add Pinia?→ 状态管理推荐，尤其涉及跨组件共享数据时 - 初始化后进项目目录，检查
package-lock.json是否生成 —— 没生成说明安装中断，删掉重来
Volar 插件启用必须做两件事
VSCode 默认不识别 <script setup></script> 和组件属性提示，光装 Volar 不够，必须激活语言服务。
- 禁用所有旧插件：特别是
Vetur，它与 Volar 冲突，会导致v-model提示失效、definePropshover 看不到类型 - 打开命令面板（
Ctrl+Shift+P），输入Volar: Take Over Mode并执行 —— 这是关键一步，否则插件不接管 .vue 文件 - 关闭 VSCode 设置里的
typescript.preferences.includePackageJsonAutoImports，否则import { ref } from 'vue'可能被错误补全成其他包
vite.config.ts 里配代理别写错字段
Vue3 项目用 Vite 启动，代理配置不在 vue.config.js（那是 Vue2 Webpack 的），而必须写在 vite.config.ts 的 server.proxy 字段。
立即学习“前端免费学习笔记（深入）”；
常见错误：
- 把后端地址直接写成
http://localhost:3000/api→proxy只匹配路径前缀，协议和 host 要放在target里 - 漏写
changeOrigin: true→ 导致后端收到的Host头仍是localhost:5173，被 nginx 或反向代理拒绝 - 没加
rewrite→ 请求路径带/api前缀发到后端，后端可能 404
正确写法：
server: {
proxy: {
'/api': {
target: 'http://192.168.1.100:8080',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}
项目路径和文件命名有硬性限制
VSCode + Volar 对大小写和字符敏感，不是“偶尔出问题”，而是直接导致语言服务加载失败。
- 项目路径禁止含中文、空格、大写字母 —— 例如
D:\MyProject\Vue3App会触发 Volar 无法启动 - 推荐命名方式：
my-vue-admin、shop-front，全小写 + 短横线 - 打开 VSCode 时，必须用
File → Open Folder直接打开项目根目录（不是子文件夹），否则插件不激活，<script setup></script>区域无任何提示
最常被忽略的是“打开方式”——很多人双击 .vue 文件或拖进 VSCode 窗口，这不会触发工作区语言服务，ref() 类型、v-if 指令提示全失效，重启也没用。
