nvim-lspconfig Vue 语言服务器完整配置指南：vue_ls 与 vtsls 双服务器 3 场景实战

nvim-lspconfig Vue 语言服务器完整配置指南：vue_ls 与 vtsls 双服务器 3 场景实战

【免费下载链接】nvim-lspconfigQuickstart configs for Nvim LSP项目地址: https://gitcode.com/GitHub_Trending/nv/nvim-lspconfig

nvim-lspconfig 是 Neovim 的 LSP 快速起步配置集合，内置了几百个语言服务器的默认参数。对于 Vue 项目，当前主线版本中官方推荐的服务器组合是 vue_ls（Vue 官方语言服务器）加 vtsls（TypeScript 语言服务的 Neovim 封装）。本文按场景给出可直接粘贴的配置、排障对照表和自查清单，适合第一次在 Neovim 中搭建 Vue 开发环境的读者。

先说结论：用 vue_ls + vtsls 这套组合

如果项目基于 Vue 3，直接启用 vue_ls 与 vtsls 两个服务器，并给 vtsls 挂载 @vue/typescript-plugin 插件，即可获得模板（HTML/CSS）与 script 块（TypeScript）的完整支持。旧的 volar 配置在新版 nvim-lspconfig 中已改名并标记弃用，写volar会自动映射到 vue_ls 并触发弃用警告（见 lsp/volar.lua），存量配置建议直接改名过渡。

背景知识一句话：早期 Vue 语言服务器有 "takeover mode"（接管模式），由它一个服务器承包 .vue 文件里所有代码的智能提示；v3.0.0 起该模式被移除，服务器改为 "hybrid mode"（混合模式）——只独占处理 HTML 与 CSS 部分，TypeScript 相关请求转发给外部 TS 服务器。这就是必须引入第二个服务器的原因。

安装两个服务器（需要 Node.js 与 npm 环境）：

# 全局安装 Vue 官方语言服务器与 vtsls npm install -g @vue/language-server @vtsls/language-server

适用版本：新版 nvim-lspconfig 主线（volar 已更名为 vue_ls 的版本），Neovim 0.10 及以上（vtsls 的项目根判定在 0.11.3 后行为略有差异，但配置写法一致）。

场景一：最小配置——让 .vue 文件先有基础提示

本节只解决一件事：让 .vue 文件尽快具备基本提示，适合先跑通再细调的用户。

-- 启用 Vue 官方语言服务器：负责 .vue 文件的 HTML/CSS 部分 vim.lsp.enable('vue_ls') -- 启用 vtsls：负责 script 块，建议与上一行同时启用 vim.lsp.enable('vtsls')

vue_ls 默认绑定vue文件类型，并以package.json作为项目根标记（见 lsp/vue_ls.lua）。如果只启用 vue_ls，script 块里不会有任何 TypeScript 提示——这是混合模式的设计，不是配置错误。

场景二：TypeScript 完整支持——vue_ls 与 vtsls 协同配置

这是绝大多数 Vue 3 + TypeScript 项目需要的完整形态，也是本文的重点。核心动作只有一个：把 @vue/typescript-plugin 注册进 vtsls 的 globalPlugins，并让 vtsls 接管 vue 文件类型。

-- 插件位置：@vue/language-server 包内部的 node_modules local vue_language_server_path = vim.fn.stdpath('data') .. '/mason/packages/vue-language-server/node_modules/@vue/language-server' local vue_plugin = { name = '@vue/typescript-plugin', location = vue_language_server_path, -- 必须指定，缺省会直接失效 languages = { 'vue' }, -- 必须包含 'vue'，即使 filetypes 已列出 configNamespace = 'typescript', } vim.lsp.config('vtsls', { settings = { vtsls = { tsserver = { globalPlugins = { vue_plugin } } }, }, -- 扩展 vtsls 支持的文件类型，纳入 Vue 单文件组件 filetypes = { 'typescript', 'javascript', 'javascriptreact', 'typescriptreact', 'vue' }, })

三点说明：

• location示例基于 mason.nvim v2 的安装路径。若用 npm 全局安装，可改为vue-language-server可执行文件所在目录下的node_modules/@vue/language-server；mason.nvim v1 用户可用require('mason-registry').get_package('vue-language-server'):get_install_path()取路径。
• vue_ls 侧的转发逻辑已内置：它监听tsserver/request请求，自动在当前 buffer 上寻找 ts_ls / vtsls / typescript-tools 客户端并转发，找不到时会重试 10 次。无需手写任何转发代码。
• ⚠️ 不要同时启用 vtsls 与 ts_ls，官方文档明确不建议两者并存。

场景三：Vue 2 遗留项目的兼容性参数检查

本节仅适用于仍在维护 Vue 2 代码库的团队。vue_ls 默认按 Vue 3 处理，Vue 2 项目需要显式声明 target，并确认编译器包版本配套。

-- 告诉语言服务器按 Vue 2 语法解析模板 vim.lsp.config('vue_ls', { settings = { vue = { target = 2 } }, }) vim.lsp.enable('vue_ls')

若模板仍报语法错误，💡 优先检查项目依赖：需要@vue/compiler-sfc的 2.x 版本，而不是 3.x。

场景四：大型项目——按需加载与 Mason 统一管理

面向多包大仓库、或希望降低 Neovim 启动开销的用户。思路是延迟到打开 Vue 文件时才拉起服务器，并交给 mason.nvim 统一安装，省去手写安装路径。

-- 按需加载：打开 vue 文件时才启用两个服务器 vim.api.nvim_create_autocmd('FileType', { pattern = 'vue', callback = function() vim.lsp.enable('vue_ls') vim.lsp.enable('vtsls') end, })

-- 由 mason.nvim 统一安装与管理，场景二的 location 路径即由此而来 require('mason').setup() require('mason-lspconfig').setup({ ensure_installed = { 'vue_ls', 'vtsls' } })

monorepo 无需特殊处理：vtsls 会自动为每个子包定位对应的 tsconfig.json / jsconfig.json，不会为每个包多开实例（见 lsp/vtsls.lua 的 root_dir 逻辑）。建议整个工作区使用同一版本的 TypeScript。

症状诊断表

按症状对号入座，从上往下逐行核对：

配置完成后的自查清单

逐项打勾，全部通过即可收工：

• vue_ls 与 vtsls 均已通过vim.lsp.enable启用
• vue_plugin.languages包含'vue'
• vtsls 的filetypes包含'vue'
• 没有同时启用 ts_ls 与 vtsls
• :checkhealth lsp中，两个服务器对 .vue buffer 均显示已附着

延伸阅读

• 全部内置服务器的完整文档：doc/configs.md
• vue_ls 默认配置与请求转发源码：lsp/vue_ls.lua
• vtsls 默认配置，含 Vue 插件示例与 monorepo 说明：lsp/vtsls.lua

如配置中遇到问题，建议直接在 nvim-lspconfig 项目仓库提交 issue，附上:checkhealth lsp的输出与 Neovim 版本，方便维护者复现。

【免费下载链接】nvim-lspconfigQuickstart configs for Nvim LSP项目地址: https://gitcode.com/GitHub_Trending/nv/nvim-lspconfig