企业官网建设流程全解析

1. Vue3 项目里 VSCode 插件到底该装哪个

如果你正在用 Vue3 写项目，打开 VSCode 的扩展面板搜「Vue」，大概率会看到两个名字很像的插件：Vue Volar extension Pack 和 Vetur。很多人第一次装插件时随手点了 Vetur，结果写<script setup>时类型提示时有时无，模板里绑定的变量标红，defineProps的参数点进去是any，改半天代码也不知道问题出在编辑器还是自己写错了。

这个场景的核心矛盾其实很简单：Vetur 是为 Vue2 时代设计的插件，它内置的模板解析和 TypeScript 处理逻辑跟 Vue3 的<script setup>、defineProps、defineEmits这套组合拳并不完全对齐。Vue 官方在 Vue3 推出后，把语言支持拆成了 Volar 体系，也就是现在的 Vue - Official（旧称 Volar）。而 Vue Volar extension Pack 是一个扩展包，它把 Vue3 开发常用的一批插件打包在一起，装一次就能覆盖语法高亮、模板类型检查、TS 接管、格式化等需求。

所以这篇内容要解决的问题很具体：在 Vue3 项目里，怎么用 Vue Volar extension Pack 一次装好，怎么在 settings.json 里把 Vetur 禁用掉、让 TypeScript 服务正确接管.vue文件，以及装完之后怎么验证类型提示和模板校验真的生效了。适合刚从 Vue2 迁到 Vue3 的开发者，也适合那些「插件装了但总觉得没生效」的人。下面按我实际配置的顺序来写，每一步都能直接复制。

2. 装扩展包之前先把 Vetur 处理干净

Vue Volar extension Pack 本身是一个「扩展包」类型的插件，安装它会自动带上几个依赖插件，比如 Vue 语言特性支持、TypeScript 的 Vue 插件等。但这里有个前提：如果你的 VSCode 里已经装了 Vetur，必须先禁用它，否则两个插件会同时尝试接管.vue文件的语言服务，表现就是提示重复、跳转错乱、保存时格式化互相打架。

操作路径是：打开 VSCode 左侧扩展面板，搜索Vetur，点进插件详情页，在「禁用」下拉里选择「禁用（工作区）」或直接禁用。如果你确定以后都不再用 Vue2 项目，直接卸载也可以。禁用比卸载更稳妥，因为有些老项目可能还需要临时切回去。

禁用完 Vetur 之后，再搜索Vue Volar extension Pack，认准发布者是 Vue 官方相关的那一个，点安装。安装完成后 VSCode 右下角可能会提示「重启以激活扩展」，点重启。重启后你可以打开命令面板（Ctrl+Shift+P），输入Developer: Show Running Extensions，确认列表里 Vetur 是 disabled 状态，而 Volar 相关插件是 activated。

这一步看起来简单，但实际踩坑最多。我见过有人装完 Volar 发现没效果，最后查出来是 Vetur 还在工作区级别启用着，两个插件抢同一个文件类型。所以顺序一定是：先禁 Vetur，再装扩展包，最后重启。

3. settings.json 可复制骨架：Volar 启用与 TS 接管

插件装好后，真正决定体验的是工作区的.vscode/settings.json。Vue3 项目建议把配置写进项目根目录的.vscode/settings.json，这样团队里每个人拉下来都是一致的，不会出现「我这有提示你那没有」的情况。下面这份骨架可以直接复制，我按功能分了段，每段都标了作用。

{ // 让 Volar 接管 .vue 文件的语言服务 "vue.server.hybridMode": true, // 禁用 Vetur 的模板检查，避免和 Volar 冲突 "vetur.validation.template": false, "vetur.validation.script": false, "vetur.validation.style": false, // TypeScript 使用工作区版本，保证和项目依赖一致 "typescript.tsdk": "node_modules/typescript/lib", "typescript.enablePromptUseWorkspaceTsdk": true, // 让 Volar 的 TS 插件接管 .vue 里的类型检查 "vue.server.includeLanguages": ["vue"], // 保存时用 Volar 格式化，不用 Vetur "[vue]": { "editor.defaultFormatter": "Vue.volar" }, // 模板里也开启类型提示 "vue.inlayHints.missingProps": true, "vue.inlayHints.inlineHandlerLeading": true, // 关闭 Vetur 对 .vue 的格式化接管 "vetur.format.enable": false }

这里有几个参数值得单独说。vue.server.hybridMode设为 true 是让 Volar 在混合模式下工作，对大多数 Vue3 项目兼容性更好。typescript.tsdk指向项目本地的 TypeScript，而不是 VSCode 自带的版本，这一步很关键——如果你项目里装的是 TypeScript 5.x，而 VSCode 内置的是旧版本，类型提示就会出现「明明类型对却报错」的怪现象。typescript.enablePromptUseWorkspaceTsdk设为 true 后，VSCode 会弹窗问你要不要用工作区版本，选「允许」即可。

vue.server.includeLanguages确保.vue文件被纳入 Volar 的语言服务范围。[vue]段里的editor.defaultFormatter指定用 Volar 格式化，避免保存时 Vetur 跳出来抢活。最后vetur.format.enable设为 false 是双保险，即使 Vetur 没完全禁用，也不让它格式化。

如果你用的是 pnpm 或 yarn 的 PnP 模式，node_modules/typescript/lib路径可能不存在，这时候需要改成实际的 TS 路径，或者用typescript.tsdk指向.yarn/sdks/typescript/lib。这个细节后面排障部分会再提。

4. 新建 .vue 文件验证类型提示与模板校验

配置写完后，别急着关掉 settings.json，先做一次验证，确认 Volar 真的在工作。验证分三步：类型提示、模板校验、跳转定义。

第一步，在src/components下新建一个DemoCard.vue，写入下面这段代码：

<script setup lang="ts"> interface User { id: number name: string email?: string } const props = defineProps<{ user: User count: number }>() const emit = defineEmits<{ (e: 'update', id: number): void }>() function handleClick() { emit('update', props.user.id) } </script> <template> <div class="card"> <h3>{{ user.name }}</h3> <p>{{ user.email }}</p> <button @click="handleClick">更新 {{ count }}</button> </div> </template>

写完后把鼠标悬停在props.user上，应该能看到User类型的完整结构提示，包括id: number、name: string、email?: string。如果只显示any或者没有提示，说明 TS 服务没接管成功，回到 settings.json 检查typescript.tsdk路径。

第二步，验证模板校验。在<template>里故意把user.name改成user.nickname，这时 Volar 应该在这个变量下方画红色波浪线，悬停提示类似「Property 'nickname' does not exist on type 'User'」。这就是模板类型检查生效的标志。如果没有任何报错，说明模板校验没开，检查vue.server.hybridMode和vue.server.includeLanguages是否配置正确。

第三步，验证跳转。按住 Ctrl（macOS 是 Cmd）点击模板里的handleClick，应该能直接跳到<script setup>里的函数定义。点击user.name里的name，应该跳到User接口的name字段。跳转正常，说明语言服务已经完整接管。

这三步都通过后，你可以在终端跑一次vue-tsc --noEmit，确认命令行类型检查和编辑器提示一致。如果编辑器不报错但vue-tsc报错，通常是 VSCode 用的 TS 版本和项目不一致，回到typescript.tsdk那一段处理。

5. 本篇常见错排查：Vetur 残留与 TS 版本不一致

配置过程中最容易遇到三类问题，我按出现频率排一下。

第一类是 Vetur 残留导致的提示冲突。表现是.vue文件里同一个变量出现两条提示，或者保存时格式化结果每次不一样。排查方法是打开命令面板，运行Developer: Show Running Extensions，看 Vetur 是否还在 activated 列表里。如果在，说明工作区级别的禁用没生效，去.vscode/settings.json里加一行"vetur.enable": false，然后重启 VSCode 窗口（不是重启整个编辑器，用Developer: Reload Window更快）。

第二类是 TypeScript 版本不一致。表现是编辑器里类型提示正常，但终端vue-tsc报一堆类型错误，或者反过来。根因是 VSCode 内置 TS 版本和项目node_modules/typescript版本不同。解决方式是确认typescript.tsdk指向的路径真实存在，然后在 VSCode 里按 Ctrl+Shift+P 输入TypeScript: Select TypeScript Version，选择「Use Workspace Version」。选完后右下角会显示当前使用的 TS 版本号，和package.json里对得上就对了。

第三类是defineProps泛型不识别。表现是写了defineProps<{ foo: string }>()但foo在模板里提示不存在。这通常是 Volar 版本过旧，或者项目里同时装了@volar/vue-language-plugin-prettier之类的旧包。处理方式是升级 Vue Volar extension Pack 到最新版，然后检查package.json里有没有残留的 Volar 旧依赖，有就删掉，重新pnpm install。

还有一个不太常见但会遇到的：monorepo 里 TS 路径解析错乱。表现是子包的.vue文件提示找不到父包的类型。这时候需要在项目根目录的tsconfig.json里配好paths，并确保 VSCode 打开的是根目录而不是子包目录。Volar 的 TS 插件会读取最近的tsconfig.json，打开错目录就会用错配置。

6. 把配置固化下来，后续接入更省事

上面这套配置跑通后，建议把.vscode/settings.json提交到 Git 仓库，同时在.vscode/extensions.json里加上推荐插件，这样团队新人拉下代码后 VSCode 会直接提示安装 Vue Volar extension Pack，不用再口头交代「别装 Vetur」。

{ "recommendations": [ "Vue.volar" ], "unwantedRecommendations": [ "octref.vetur" ] }

unwantedRecommendations这一项会提示用户不要装 Vetur，从源头上减少冲突。如果你后续要在项目里接入模型能力做代码补全或对话式调试，可以先把 API Key 和接入文档准备好，模型对话入口在 https://taotoken.net/api-keys ，接入文档在 https://taotoken.net/doc ，需要长期跑编码任务或 Agent 的话可以看 Coding Plan：https://taotoken.net/coding-plan 。这些和 Volar 配置不冲突，属于项目跑起来之后的下一步。

回到插件本身，Vue Volar extension Pack 的价值就在于「一次装好、少踩坑」。它把 Vue3 开发需要的语言服务、TS 接管、模板校验打包在一起，你只需要做两件事：禁掉 Vetur，写好 settings.json。剩下的类型提示和模板校验，新建一个.vue文件就能验证。如果验证时发现提示不对，优先查 Vetur 是否残留、TS 版本是否一致，这两个点覆盖了绝大多数问题。