Vetur 常见问题排查指南：从降级安装、崩溃修复到项目配置的完整 FAQ 实战手册

• 开发工具
• IDE
• 前端

导读

本文以 Vetur（VS Code 的 Vue 工具链扩展）官方 FAQ 为骨架，系统梳理开发者在日常使用中最常遇到的十余类问题：包括扩展降级安装、语法高亮失效、语言服务器（VLS）崩溃、webpack 别名不被识别、TypeScript 类型报错、模板自动补全失灵、Vue 组件导入失败，以及tsconfig.json/jsconfig.json/package.json缺失引发的各类告警。每类问题都给出可直接照做的解决步骤，并结合仓库源码（如 server/src/services/vls.ts、server/src/config.ts、client/commands/doctorCommand.ts）说明其底层原理，帮助你快速定位、修复问题，并把 Vetur 调校到最佳状态。

一、安装旧版本 Vetur（降级）

有时新版本会引入你不想碰到的 bug，降级到可用的旧版本是最直接的规避手段。步骤如下：

1. 在 VS Code 设置中关闭扩展自动更新："extensions.autoUpdate": false。
2. 到 CHANGELOG.md 中查阅历史版本，找到你想安装的版本号，并下载对应版本的 VSIX 文件。
3. 在 VS Code 中执行Install from VSIX命令手动安装该 VSIX（进入扩展视图后通过菜单触发）。

当前仓库package.json中记录的扩展版本为0.37.3，发布者（publisher）为octref。手动安装旧版 VSIX 时，VS Code 会自动降级并覆盖当前安装，安装完成后建议重启窗口（Developer: Reload Window）使新版本生效。

二、没有语法高亮、语言功能全部失效

如果.vue文件既没有语法高亮，也没有任何补全、诊断等语言功能，通常只有两种原因：

原因一：其他扩展与 Vetur 冲突

某些扩展也会向 VS Code 贡献vue语言支持，导致与 Vetur 的 language registration 冲突。处理方式：在扩展面板中禁用所有其他 Vue 相关的扩展（例如重复的语法高亮包、其他 Vue 语言工具等），然后重新加载窗口逐一验证。

原因二：Vetur 自身未正确安装

如果扩展安装不完整或依赖损坏，Vetur 的语言服务无法正常启动。按以下顺序尝试：

• 对 Vetur 执行Developer: Reinstall Extension命令强制重装；
• 删除 extensions 文件夹 中的 Vetur 目录后干净重装；
• （Windows）以管理员权限卸载并重新安装 Vetur；
• 若以上均无效，下载仓库 releases 中最新的预打包 VSIX 文件，通过 VSIX 方式安装。

从源码实现看，Vetur 激活后会在 client/vueMain.ts 中通过client.start()启动 Vue Language Server（语言服务器模块位于server/dist/vueServerMain.js），如果扩展文件缺失或依赖损坏，这一初始化过程会失败，进而表现为高亮与语言功能整体失效。

三、Vetur 崩溃（VLS Crash）

3.1 报错cannot find module <some-module>

这类错误通常是 VS Code 在版本升级时没有正确更新 Vetur 的依赖导致的。解决办法：进入 Vetur 的客户端代码安装目录，手动执行yarn或npm install重新安装依赖。

各平台默认路径如下（<version>为当前安装的扩展版本号）：

• Windows：%USERPROFILE%\.vscode\extensions\octref.vetur-<version>\client
• macOS：~/.vscode/extensions/octref.vetur-<version>/client
• Linux：~/.vscode/extensions/octref.vetur-<version>/client

也可以直接卸载后重新安装 Vetur。

3.2 与内存、CPU 相关的问题

如果崩溃提示与内存或 CPU 占用有关，通常是 Vetur 加载了太多非 Vue 相关代码导致的。建议在项目根目录添加jsconfig.json或tsconfig.json，并且只 include Vue 相关代码，让 TypeScript 语言服务缩小扫描范围，详细配置方法见 docs/guide/setup.md#project-setup。

四、Vetur 无法识别通过 webpack alias 导入的组件

当项目使用 webpack 的resolve.alias（例如'@': 'src'）来导入组件时，Vetur 依赖 TypeScript 的模块解析能力，因此你必须在jsconfig.json或tsconfig.json中同步配置 path mapping，才能让补全、跳转、诊断正确工作。

webpack 侧的配置（示意）：

// Webpack module.exports = { resolve: { alias: { '@': 'src' } } }

TypeScript 侧的对应配置：

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

实际项目中，baseUrl与paths的具体值应与你仓库的真实目录结构对齐。完整的路径映射示例（包括components/*别名以及目录树说明）可参考 docs/guide/setup.md#path-mapping。

源码层面：Vetur 会读取项目根目录的tsconfig.json/jsconfig.json来构造 TypeScript 语言服务（见 server/src/services/vls.ts 中ProjectConfig.tsconfigPath的解析逻辑），paths与baseUrl正是 TypeScript 语言服务做模块解析的依据，因此别名配置必须两边保持一致。

五、Property 'xxx' does not exist on type 'CombinedVueInstance'报错

在 Vue 2 + TypeScript 项目中，模板插值或组件代码中大量出现此类错误时，根源在 Vue 官方类型与 TypeScript 的兼容性问题（相关 upstream issue 见 vuejs/vue#8721、vuejs/vue#9873 与 microsoft/TypeScript#30854，此处仅作背景说明，不再展开外部链接）。

可采用以下任一种方式绕过：

1. 为每个 computed 属性标注返回类型：可以通过 JSDoc 注释 或 TS 类型标注（Annotating Return Types）方式补全返回类型，让模板插值服务拿到确定的类型信息；
2. 关闭模板插值校验：设置vetur.validation.interpolation: false，代价是模板区域不再做类型错误检查；
3. 降级 TS 版本并启用工作区依赖：将 TypeScript 降到 3.4 之前，并开启vetur.useWorkspaceDependencies，代价是无法使用可选链（optional chaining）等新版 TS 语法；
4. 迁移到 Composition API：从根本上绕开 Vue 2 options API 与 TS 的类型推导困境。

延伸：模板插值自动补全失效

如果你发现<template>里的插值自动补全不工作，很可能是同一类问题——computed 属性没有写返回类型。解决方法相同：为 computed 添加 JSDoc 或 TS 返回类型标注，Vetur 的模板插值服务即可正常推导出补全候选。

补充说明：vetur.validation.interpolation默认值为true（见 server/src/config.ts 中getDefaultVLSConfig()）。该开关控制的是「使用 TypeScript 语言服务校验<template>区域的插值表达式」，关闭后模板区域将不再报告插值相关的类型错误。

六、Vetur 无法识别 Vue 组件导入：import Comp from './comp'

当你在<script>中写import Comp from './comp'却无法被识别时，原因通常是导入语句缺少.vue扩展名。Vetur 依赖 TypeScript 语言服务做模块解析，而对.vue单文件组件的导入必须显式携带扩展名：

import Comp from './comp.vue'

七、TS 文件中无法导入.vue文件

在.ts文件里import xxx from 'xxx.vue'报错，是因为 TypeScript 默认不知道.vue模块的类型形状。你需要在项目的 d.ts 声明文件中补充通配符模块声明。

Vue 2 项目（shims-vue.d.ts）：

declare module '*.vue' { import Vue from 'vue' export default Vue }

Vue 3 项目（shims-vue.d.ts）：

declare module '*.vue' { import type { DefineComponent } from 'vue' const component: DefineComponent<{}, {}, any> export default component }

这两个模板同样收录在 docs/guide/setup.md#typescript 中。创建该 shim 文件后，.ts文件即可正常导入.vue组件并获得类型支持。

八、从源码构建并安装 Vetur

如果你是开发者，希望基于源码自行构建扩展，需要先安装vsce（VS Code 扩展打包工具），然后克隆仓库并编译：

git clone https://github.com/vuejs/vetur cd vetur yarn yarn compile vsce package

说明：当前仓库的根 package.json 中，compile脚本对应rollup -c rollup.config.js；postinstall会自动进入server与vti子目录安装依赖。这里给出的git clone地址仅为还原官方 FAQ 原文操作步骤，本地实际使用的仓库路径以你的检出位置为准。

构建完成后，你会得到vetur-{version}.vsix文件，在 VS Code 中通过Install from VSIX命令安装即可。

九、让 Vetur 使用工作区的 TypeScript 版本

如果.vue文件中使用的 TypeScript 版本与你node_modules中安装的版本不一致，可以开启Vetur: Use Workspace Dependencies设置，让 Vetur 使用工作区内的 TypeScript。

要点说明：

• 该设置默认值为false（Vetur 默认使用内置打包的 TypeScript，见 server/src/config.ts）；
• 开启后，Vetur 会优先使用typescript.tsdk设置指定的路径；若未定义，则回退到node_modules/typescript；
• 该机制让 Yarn PnP 等工具可以挂载自己的自定义解析器。

源码层面：在 server/src/services/dependencyService.ts 中，createDependencyService会依据useWorkspaceDependencies决定加载内置 TypeScript 还是从node_modulesPaths中查找工作区 TypeScript；server/src/services/vls.ts 中的getProjectService也以该开关控制nodeModulesPaths的收集行为。受此设置影响的运行时依赖包括typescript、prettier、@prettier/plugin-pug、prettier-eslint、prettier-tslint、stylus-supremacy等（见根 package.json 中vetur.useWorkspaceDependencies的官方描述）。

十、Vetur 运行缓慢

Vetur 变慢时，可以直接执行命令Vetur: Restart VLS (Vue Language Server)重启语言服务器，让 VLS 释放旧状态、重新加载项目。

该命令在源码中对应vetur.restartVLS（注册于 client/vueMain.ts），其实现为：停止当前 LanguageClient → 重新start()→ 等待onReady()，整个过程会显示初始化进度。

如果问题持续出现，建议按照性能问题报告模板附上 profile 提交 issue，帮助项目定位根因（具体模板说明见 docs/guide/FAQ.md）。

十一、告警：「Vetur can't find tsconfig.json / jsconfig.json in /xxxx/xxxxxx」

当项目根目录没有tsconfig.json或jsconfig.json时，Vetur 会使用 fallback 设置，导致部分功能不可用，例如：

• 路径别名（path alias）
• 装饰器（decorator）
• 导入 JSON（import json）

解决方式：在项目正确位置添加tsconfig.json/jsconfig.json；若无法放在根目录（如 monorepo 场景），可通过vetur.config.js指定其路径。

• 项目配置指引见 docs/guide/setup.md#project-setup
• vetur.config.js进阶用法见 docs/guide/setup.md#advanced

调试与关闭告警：

• 使用Vetur: show doctor info命令查看诊断信息；
• 在 VS Code 设置中设置vetur.ignoreProjectWarning: true关闭此告警（默认false，配置项定义见根 package.json）。

⚠️ 注意：如果你根本不需要「路径别名 / 装饰器 / 导入 json」这些能力，可以直接关闭该告警，不影响日常使用。

源码层面：此告警由 server/src/services/vls.ts 的warnProjectIfNeed触发。它通过findConfigFile（基于 TypeScript 的ts.findConfigFile，见 server/src/utils/workspace.ts）查找配置文件，找不到时会向用户弹出带Learn More按钮的警告消息；若vetur.ignoreProjectWarning为true则直接跳过。tsconfigPath还会参与决定语言服务的功能范围，所以「找不到配置 → 功能降级」是环环相扣的。

十二、告警：「Vetur can't find package.json in /xxxx/xxxxxx」

项目根目录缺少package.json时，Vetur 无法得知安装的 Vue 版本，也无法读取其他库的 component data。此时Vetur 会假定 Vue 版本低于 2.5；如果实际版本不同，你会得到来自 TypeScript 与 eslint 模板校验的错误诊断。

解决方式：在项目正确位置添加package.json，或通过vetur.config.js指定其路径（见 docs/guide/setup.md#advanced）。

调试与关闭告警的方式同上：Vetur: show doctor info查看诊断，vetur.ignoreProjectWarning: true关闭告警。

源码层面：VLS 通过 server/src/utils/vueVersion.ts 的inferVueVersion推断 Vue 版本——优先读取package.json中dependencies.vue/devDependencies.vue的版本号，其次尝试require.resolve('vue/package.json')读取 node_modules 中的实际版本；两者都失败时回退为VPre25（< 2.5），与 FAQ 描述一致。此外，当检测到 Vue 3 项目时，VLS 还会额外弹出提示，建议使用 Vue 官方推荐的 Vue Language Features (Volar) 扩展（见 server/src/services/vls.ts）。

十三、告警：「Vetur found xxx, but they aren't in the project root」

Vetur 找到了某个配置文件（如tsconfig.json、jsconfig.json或package.json），但它不在项目根目录。此时该文件「可能并不是你真正想要的」，如果实际用错了文件，后果与前两类告警相同（功能降级或错误诊断），相关背景见 docs/guide/FAQ.md#vetur-can-t-find-tsconfig-json-jsconfig-json-in-xxxx-xxxxxx 与 docs/guide/FAQ.md#vetur-can-t-find-package-json-in-xxxx-xxxxxx。

解决方式：将配置文件放到正确位置，或通过vetur.config.js指定其路径（见 docs/guide/setup.md#advanced）。

调试与关闭方式：Vetur: show doctor info查看调试信息；vetur.ignoreProjectWarning: true关闭告警。

源码层面：warnProjectIfNeed会在「不存在vetur.config.js且解析到的配置文件不在项目根目录」时弹出该告警（isExistVeturConfig为false时，根目录下的tsconfig.json/jsconfig.json/package.json才是预期位置），同时还会用accessSync检查文件是否可读，不可读时给出Vetur can't access ...错误提示。

十四、如何查看 Vetur 的完整诊断信息（Doctor 机制）

FAQ 多次提到Vetur: show doctor info命令，它对应vetur.showDoctorInfo（注册于 client/vueMain.ts，实现于 client/commands/doctorCommand.ts）。

工作流程：

1. 客户端校验当前活动文件是否为.vue文件，否则提示失败信息；
2. 客户端向语言服务器发送$/doctor请求（携带当前文件名）；
3. 服务端在 server/src/services/vls.ts 的setupCustomLSPHandlers中响应：收集当前项目的Vue 版本、配置文件根路径、项目根路径，以及全部活动项目与项目配置列表，格式化后返回 JSON；
4. 客户端弹出模态消息展示前 1000 字符，并提供Ok / Copy两个操作，选择 Copy 可将完整诊断结果写入剪贴板。

在排查「找不到配置文件」「版本推断错误」「VLS 加载异常」等问题时，先跑一次 Doctor 拿到这些 JSON 信息，往往能立刻定位症结。

附录：与 FAQ 强相关的配置速查

以下配置项在 FAQ 中被反复引用，均可写入 VS Code settings 或vetur.config.js的settings字段（后者优先级更高，见 docs/reference/Readme.md）。默认值与类型以当前仓库为准：

以上默认值可在 server/src/config.ts 的getDefaultVLSConfig()与根 package.json 的contributes.configuration.properties中交叉验证；vetur.config.js的完整字段说明（settings、projects[].root/package/tsconfig/snippetFolder/globalComponents）见 docs/reference/Readme.md 及设计草案 rfcs/001-vetur-config-file.md。

• 开发工具
• IDE
• 前端