必须开启Volar Take Over Mode并启用experimental.vueMacros，同时在tsconfig.json中添加"types": ["vue"]并重启TS服务，否则defineProps报错、ref解构类型丢失为any。

VSCode 里 Vue 代码片段没反应、defineProps 不提示、ref 解构后类型是 any，基本不是插件没装，而是 Volar 的语言服务没真正接管或宏支持没开。

为什么 defineProps 报错 “Cannot find name”

这不是语法错误，是 TypeScript 编译上下文缺失 Vue 类型声明。Volar 依赖 TS 加载 @vue/runtime-core 提供的全局接口，而这个加载前提是 tsconfig.json 显式声明了 "types": ["vue"]。

• 必须在项目根目录 tsconfig.json 的 compilerOptions 中添加该字段，不能只靠插件自动推导
• JS 项目用 jsconfig.json 时，要写 "types": ["vue/types"] 并确保已安装 @vue/runtime-core
• 改完配置后必须执行 Ctrl+Shift+P → Restart TS server，重载窗口（Reload Window）不够
• 如果用了 pnpm 或 Yarn PnP，Volar 可能找不到类型包，临时补装：pnpm add -D @vue/language-core

ref() 解构后类型丢失，const { count } = reactive({ count: 0 }) 显示 any

Volar 默认对 script setup 的宏支持是保守的，reactive 解构不触发完整类型推导，除非开启实验性宏支持。

• 打开 VSCode 设置，搜索 volar.experimental.vueMacros，勾选启用
• 该选项影响 defineProps 泛型解析、ref 自动解包、computed 类型继承等关键行为
• 必须重启整个 VSCode 窗口（不是重载），否则设置不生效
• 注意：大项目首次启动会略慢，因为 Volar 要重建更细粒度的模板 AST 索引

路径别名（如 @/components/HelloWorld.vue）Ctrl+Click 跳转失败

Volar 不读 vite.config.ts 里的 resolve.alias，它只认 tsconfig.json 或 jsconfig.json 中的 baseUrl 和 paths 配置。

vue-component-analyzer

递归分析 Vue 项目组件依赖，从入口文件生成组件层级图，支持 Vue 2/3，输出组件名、文件路径和属性。适用于分析组件结构、排查依赖或了解项目架构。

下载

立即学习“前端免费学习笔记（深入）”；

• 确认 tsconfig.json 的 compilerOptions 包含：

  "baseUrl": ".",
  "paths": {
    "@/*": ["src/*"]
  }
  

• paths 的键必须和 import 路径完全匹配，比如用 ~/utils 就得加 "~/*": ["src/utils/*"]
• 如果项目用的是 jsconfig.json，同样要配 baseUrl + paths，且 include 必须包含 src/**/*.vue
• Volar 的 Take Over Mode 必须开启，否则路径映射不会被应用到 .vue 文件的 template 区域

.vue 文件格式化后缩进错乱、属性换行异常

Prettier 对 Vue 单文件组件的模板语法支持有限，尤其在 <template> 块中容易把 v-if、@click 换行成不可读形式。Volar 内置的格式化器才是 Vue 官方推荐方案。

• 在 VSCode 设置中搜索 prettier.vue，清空 Prettier: Vue Files Suffixes 字段（留空）
• 为 [vue] 文件类型单独指定默认格式化器："[vue]": { "editor.defaultFormatter": "vue.volar" }
• 禁用 Prettier 对 .vue 的格式化，但保留它对 .js/.ts 的处理能力
• 如果用了 ESLint + source.fixAll.eslint，确保 .eslintrc 已启用 plugin:vue/vue3-recommended，否则修复命令可能忽略模板规则

最常被跳过的一步是确认右下角状态栏显示的是 Vue (Volar)，而不是 Vue (Vetur) 或纯 HTML —— 这个状态决定了整个语言服务链是否真正启动，所有后续配置都建立在这个基础上。