用 npm create vue@latest 初始化项目最省事，官方已弃用全局 vue-cli，create-vue 支持 TypeScript、Pinia 等可选功能；注意 npm 版本、代理配置、响应式声明、路径大小写及类型文件修改后需重启 Vite。
用 npm create vue@latest 初始化项目最省事
Vue 官方脚手架已经不再推荐全局安装 vue-cli，create-vue 是当前唯一维护的初始化方式。它默认支持 TypeScript、Pinia、Vitest、ESLint，还能选要不要 router 和 prettier——这些选项直接影响后续开发体验，别全按回车跳过。
常见错误现象：npm init vue@latest 报 404 或卡住，其实是 npm 版本太低（npx create-vue@latest 更稳。
- 执行前先确认 Node.js ≥ 16.12，否则
create-vue启动失败 - 选 “Add TypeScript?” 时建议选 Yes，Vue3 的类型推导依赖 TS，后期补成本高
- 选 “Add Vue Router for Single Page Application routing?” 如果是管理后台或有多个视图，必须选；纯静态页可不选
- 初始化后进目录，
npm install前先检查package-lock.json是否生成，没生成说明安装中断了，得删掉重来
vue-language-features 插件不是可选项，是必装项
VSCode 默认不识别 .vue 文件里的 <script setup></script> 语法和组件属性提示。光装 Volar 不够，必须启用它的语言功能插件，否则 ref() 类型不显示、v-model 绑定没智能提示、defineProps 参数 hover 看不到类型。
容易踩的坑：Volar 和旧版 Vetur 冲突，必须禁用 Vetur；且 VSCode 设置里要关掉 typescript.preferences.includePackageJsonAutoImports，否则 import { ref } from 'vue' 可能被错误自动补全成其他包。
立即学习“前端免费学习笔记（深入）”；
Element Plus Vue3 桌面组件库。在开发 Vue 3.x 页面时调用，使用 Element Plus 组件（如 el-button、el-input、el-form、el-table 等）。
- 插件市场搜 “Volar”，装官方发布的那个（作者是 Vue Team）
- 打开 VSCode 设置 → 搜索 “volar” → 勾选 “Vue: Enabled” 和 “TypeScript: Enabled”
- 如果
<template></template>里写v-if还没提示，重启 VSCode 并打开项目根目录（不是子文件夹），否则插件不激活
devServer.proxy 配置不对，本地调接口永远 404
Vue3 项目用 vite 启动，代理配置不在 vue.config.js（那是 Vue2 Webpack 的），而在 vite.config.ts 的 server.proxy 字段。很多人照着老教程配 devServer，结果请求根本没转发。
典型错误：把后端地址写成 http://localhost:3000/api，但 proxy 只接受路径前缀匹配，协议和 host 要在 target 里单独写；还有人漏写 changeOrigin: true，导致后端收到的 Host 头还是 localhost，被 nginx 拒绝。
- 正确写法：
server: { proxy: { '/api': { target: 'http://192.168.1.100:8080', changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, '') } } } - 测试是否生效：浏览器访问
http://localhost:5173/api/users，看 Network 面板里请求 URL 是否变成目标地址 - 如果后端是 HTTPS，target 必须写
https://，且加secure: false（仅开发环境）
热更新失效？大概率是 setup 里用了非响应式变量
改了 ref 或 reactive 数据，页面没刷新，不是 Vite 问题，而是你写了 let count = 0 这种普通变量，或者在 onMounted 里直接赋值给未声明的 this.xxx（Vue3 已无 this）。
另一个高频原因：组件名含大写字母但文件名是小写（比如组件叫 MyButton.vue，但 import 写成 import mybutton from './mybutton.vue'），Vite 开发服务器不会监听这个文件变化。
- 响应式数据必须用
ref()、reactive()、computed()显式声明 - 组件引入路径大小写要和文件系统完全一致，Windows 可能不报错，但部署到 Linux 就白屏
- 改了
shims-vue.d.ts或新增自定义类型后，需重启 Vite，否则类型热更不触发
