Claude Code LSP 配置：插件加语言服务器，不用 ENABLE_LSP_TOOL

截至 2026 年 11 月 2 日（Claude Code 2.1.316），给 Claude Code 配 LSP 只有两件事：先在电脑上装好你那门语言的语言服务器程序，再装官方市场里对应的代码智能插件（code intelligence plugin）。以 TypeScript 为例，先运行 npm install -g typescript-language-server typescript，再在 Claude Code 里输入 /plugin install typescript-lsp@claude-plugins-official；Python、Go、Rust、Java 等语言把插件名换成下文表格里的那一个。然后开一个新会话，让 Claude 故意写错一处类型再改回来，对话里出现 Found 1 new diagnostic issue in 1 file (ctrl+o to expand) 这样一行，就说明已经生效。

旧教程里的 ENABLE_LSP_TOOL 环境变量和"打 patch"都不用再做。2026 年 11 月 2 日在 macOS 上用 2.1.316 测过，这个变量设成 0 或 1 都不改变结果，LSP 开不开只看插件装没装、启没启用。

装好之后，Claude 得到的是两样不同的东西：每次改完文件自动送过来的报错（诊断），和一个它可以调用、也可能不调用的 LSP 代码导航工具。有两个例外要先知道：在从没开过交互式会话的全新配置里，用系统终端命令 claude plugin install 安装会报 Plugin "typescript-lsp" not found in marketplace，先运行 claude plugin marketplace add anthropics/claude-plugins-official 再装；云端会话不启动语言服务器，只有本地终端会话能用上。

Claude Code LSP 是什么：插件告诉它启动谁，语言服务器要自己装

Claude Code 的 LSP 由两部分组成，最容易混的就是这两样。语言服务器是一个独立程序，比如 TypeScript 的 typescript-language-server、Python 的 pyright-langserver，和编辑器里负责跳转定义、标红报错的是同一类程序；代码智能插件只是一份配置，告诉 Claude Code 用什么命令启动这个程序、哪些扩展名交给它处理。官方插件里不带程序，在官方市场的仓库里，插件目录只有 README 和 LICENSE，启动命令写在市场的清单文件里，所以只装插件、不装程序，什么都不会发生。

按 Claude Code 代码智能插件文档，服务器跑起来后 Claude 多了两种能力。第一种是诊断：Claude 每次编辑或写入一个由该服务器处理的文件，服务器报出的类型错误、缺失的 import、它自己写出的语法错误都会送回给它，不用跑编译器。第二种是 LSP 工具，按符号查定义、引用、悬停类型、文档符号和调用层级，而不是按文本搜索。诊断是自动推送的；工具要 Claude 自己决定去调，后文会讲到它并不总是去调。这个工具是只读的，不弹权限确认，但你在权限规则里写的 Read(...) 路径限制同样管得住它。

LSP 和 MCP 不是一回事：LSP 只服务于本地代码的类型和符号，MCP 接的是外部服务和数据。想挑 MCP，看 Claude Code 最值得先加的 MCP（2026）：按工作流选第一批集成。

配置步骤：装语言服务器、装插件、用一次类型错误确认

顺序是先程序、后插件、再确认，官方文档也按这个顺序写。还没装 Claude Code 本身的，先看 Claude Code 安装教程：全平台完整设置指南（2026）。

1. 按下一节的表格装好你那门语言的语言服务器程序，然后在你平时启动 claude 的那个终端里确认它找得到：macOS 和 Linux 用 which typescript-language-server，PowerShell 用 Get-Command typescript-language-server，把程序名换成你装的那个。
2. 在这个终端里运行 claude，在 Claude Code 的输入框里输入 /plugin install typescript-lsp@claude-plugins-official，把 typescript-lsp 换成你语言的插件名。这条命令先打开插件详情面板，选 Install for you 装到你自己的用户范围（另外两项分别是装给这个仓库的所有协作者，和只在这个仓库里装给你自己）；装完的提示会告诉你插件已经生效，还是需要重新加载（做法见本节最后一段）。
3. 开一个新会话，让 Claude 在这门语言的文件里故意写一个类型错误，再把它改掉。对话里出现 Found N new diagnostic issues in M files (ctrl+o to expand) 这一行，就说明服务器启动了；没有出现，运行 /plugin，打开 Errors 标签看原因。

语言服务器不是会话一开始就运行，而是等 Claude 第一次编辑这门语言的文件时才启动，所以第 3 步一定要让 Claude 真的改一次文件。用 VS Code 扩展或桌面应用的，第 2 步改用它们自己的插件界面安装。想在系统终端里装，也可以运行 claude plugin install typescript-lsp@claude-plugins-official，不过这条命令不会替你注册官方市场，在全新配置上会失败，修法见后面的报错一节。

装完最稳的做法是开一个新会话。想留在当前会话里加载，普通的 /reload-plugins 并不会真的加载 LSP：它只提示 This reload adds the LSP tool，说明工具列表一变，下一条消息要重新读一遍整段对话、用不上提示缓存，然后让你运行 /reload-plugins --force 才生效。这一次重读为什么会让对话变贵，见 Claude Code 缓存未命中 token 成本：一次对话为什么突然变贵。

13 种语言各装哪个插件和语言服务器

官方文档列出 13 种语言，每种语言对应一个插件和一个要你自己装的程序。下表的安装命令取自官方市场里各插件的 README（仓库 2026 年 10 月 30 日的版本），其中 TypeScript 这一条在 2026 年 11 月 2 日的测试里实际跑过；装完都用上一节第 1 步的 which 确认一次。

除了 Liquid 由 Shopify 维护、官方市场代为收录，其余 12 个都由 Anthropic 维护，装法都是 /plugin install 插件名@claude-plugins-official。TypeScript 的命令同时装了 typescript 包，这一步别省：只装 typescript-language-server 而项目里又没有 typescript，服务器会在启动时直接退出（见排错表）。Java 和 Kotlin 的插件把启动等待上限设成了 120,000 毫秒，即 2 分钟，这两个服务器第一次启动要多等一阵。表里没有你的语言，跳到后面"自己写 .lsp.json"一节。

怎么确认 LSP 生效：诊断在下一轮才送到 Claude

诊断不在编辑工具的返回结果里，而是在下一轮以一段单独的消息送给 Claude，所以终端里那行 Found … new diagnostic issue 提示常常不在编辑那一行下面，而是在下一个工具行下面。看到这一行就算生效，按 Ctrl+O 能展开看具体是哪些错误。

2026 年 11 月 2 日的测试是这样跑的：macOS，Claude Code 2.1.316，typescript-language-server 6.0.2，配置目录与日常环境隔离，模型接口换成本地 mock 接口，没有调用真实模型，因此能原样看到 Claude Code 发给模型的每一个请求。测试项目只有 3 个文件。让 Claude 写入一个调用 priceWithTax("100", 0.1) 的 checkout.ts 后，服务器 69 毫秒完成初始化，约 0.58 秒后报出错误；这个错误没有出现在写入工具的结果里，而是附在下一个请求里，原文如下：

<new-diagnostics>The following new diagnostic issues were detected:

checkout.ts:
  ✘ [Line 3:43] Argument of type 'string' is not assignable to parameter of type 'number'. [2345] (typescript)</new-diagnostics>

同一组测试里还有三点值得知道。终端界面里，Found 1 new diagnostic issue in 1 file (ctrl+o to expand) 显示在下一行"Ran 1 shell command"下面，而不是写入文件那一行下面，官方文档说的是"出现在引入错误的那次编辑下面"，实际会晚一行。把错误改掉之后，服务器报告 0 个问题，Claude Code 直接跳过，Claude 不会收到"已修复"之类的消息。LSP 工具一开始并不在工具列表里：Claude 第一次写入或读取 .ts 文件后，Claude Code 才告诉模型有一个可以通过 ToolSearch 加载的延迟工具 LSP，模型要先加载它才能调用。

没有提示行不一定说明代码没错。Scott Spence 在 2026 年 10 月 10 日重新测试 Claude Code LSP 的文章里记录，在两个很短、编辑就是最后一步的会话里，类型错误一直没有报出来；在较长的会话里，错误约 30 秒后才出现。从 shell 改动的文件同样不会报。所以确认时让 Claude 改完文件再做一步别的事（比如跑一条命令），提示行才有机会出现；要交付的改动，仍以跑一次类型检查或构建为准。

"LSP plugin recommendation" 弹窗：四个选项选哪个

弹窗推荐的插件正好是你要的语言，就选 Yes, install，然后开一个新会话。弹窗出现的条件是：语言服务器程序已经在 PATH 上，而用它的插件还没装，Claude 刚编辑了一个对应扩展名的文件；一个会话最多弹一次，多个市场都有插件时优先推荐官方市场的，云端会话里不会弹。

2026 年 11 月 2 日在交互式终端里复现过：卸掉 typescript-lsp、保留 PATH 上的 typescript-language-server，让 Claude 写一个 .ts 文件，这一轮结束后立刻弹出标题为"LSP plugin recommendation"的窗口，写着 Plugin: typescript-lsp、Marketplace: claude-plugins-official、Triggered by: .ts files。插件装着但处于禁用状态时，同样的操作不会弹窗，所以你自己禁用过的插件不会被再推荐一次，要用就运行 /plugin enable typescript-lsp@claude-plugins-official。选 Yes, install 之后，claude plugin list 显示插件已装在用户范围、处于启用状态。

弹窗 30 秒内不选，就算"忽略"一次，次数跨会话累计；累计忽略 5 次后，效果和选了 Disable all LSP recommendations 一样，恢复办法也一样，删掉上表最后一行那两个键。

还要加 ENABLE_LSP_TOOL、打 patch 吗：2.1.316 上不起作用

不用加，加了也没有效果。2026 年 11 月 2 日在 2.1.316 上两个方向都试过：插件启用时设 ENABLE_LSP_TOOL=0，Claude 照样拿到 LSP 工具，诊断照样送达；插件禁用时设 ENABLE_LSP_TOOL=1，没有 LSP 工具，调试日志里写着 Total LSP servers loaded: 0。设置文件里留着这个变量不会出错，但它什么也不决定。

这个变量来自 LSP 还没写进文档的时期。karanbansal.in 2026 年 2 月 28 日的 Claude Code LSP 教程至今仍让读者在 settings.json 里写 "env": {"ENABLE_LSP_TOOL": "1"}，并说明这是来自 GitHub issue #15619 的社区做法；现在官方环境变量列表里没有这一项。Scott Spence 在前面那篇 2026 年 10 月 10 日的文章里也写到，他把变量删掉后，LSP 在 2.1.296 上照常加载。打补丁的教程同样属于 2026 年初：之后的 changelog 里，2.1.0（2026 年 1 月 7 日）修复了没配服务器时 LSP 也被启用的问题，2.1.74（2026 年 3 月 12 日）修复了 Windows 上文件路径格式错误导致 LSP 不工作的问题。照着旧教程折腾无果的，删掉变量和补丁，升级到当前版本，按上面的步骤装插件即可。

报错 Plugin "typescript-lsp" not found in marketplace：先添加官方市场

看到这条报错，说明你的配置里还没有注册官方市场 claude-plugins-official，先添加市场再安装插件。官方市场通常在你第一次启动交互式终端会话时自动注册；只用过 VS Code 扩展、组织策略禁止这个来源、设置了 CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL，或者上一次注册失败还在等待重试，它都不会出现。Claude Code 插件排错文档还写明，claude plugin 这组系统终端命令从不替你注册它。

2026 年 11 月 2 日在一份全新的配置上，直接在系统终端运行 claude plugin install typescript-lsp@claude-plugins-official，得到的就是这条报错：

✘ Failed to install plugin "typescript-lsp@claude-plugins-official": Plugin "typescript-lsp" not found in marketplace "claude-plugins-official". Your local copy may be out of date — try `claude plugin marketplace update claude-plugins-official`.

报错建议的 claude plugin marketplace update claude-plugins-official 也失败了，返回 Marketplace 'claude-plugins-official' not found. Available marketplaces: anthropic-plugin-directory，因为根本没有这个市场可以更新。真正修好的是先添加市场，再装插件：

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install typescript-lsp@claude-plugins-official

第一条输出 ✔ Successfully added marketplace: claude-plugins-official，第二条输出 ✔ Successfully installed plugin: typescript-lsp@claude-plugins-official (scope: user)。在 Claude Code 会话里操作也一样，输入 /plugin marketplace add anthropics/claude-plugins-official 后再 /plugin install。报错是 Marketplace "claude-plugins-official" not found 的，原因和修法相同；如果是组织策略禁止了这个来源，就要找管理员。

LSP 装了没反应：按症状找原因

先记住一点：语言服务器起不来时，Claude 本身收不到任何错误文字。2026 年 11 月 2 日的测试里，程序不在 PATH 上、或者项目缺少 typescript 包时，Claude 照样被告知有 LSP 工具可用，却既没有诊断，也没有报错，所以问 Claude"LSP 好了没"得不到答案。要看原因，去 /plugin 的 Errors 标签，或者用 claude --debug 启动后看调试日志。

表里第一、二行的调试日志原文来自 2026 年 11 月 2 日的测试（2.1.316），完整写法分别是 LSP server plugin:typescript-lsp:typescript failed to start 和 Could not find a valid TypeScript installation. Please ensure that the "typescript" dependency is installed in the workspace or that a valid tsserver.path is specified.；装好缺的程序后，Claude Code 会在下一次编辑同类文件时重试。server is starting 同样来自 2026 年 11 月 2 日的测试：mock 接口在毫秒级就回复，让 Claude 在第一次编辑后立刻发起跳转定义、查引用、悬停和符号搜索，四个调用都返回 Cannot send notification to LSP server … server is starting，等 4 秒后再调就全部正常。真实模型比 mock 慢得多，很少这么快发起调用，但这个启动窗口确实存在。云端会话和本地会话的区别，见 Claude Code 有网页版吗：先分清云端 Web、本地控制和第三方界面。

首次 findReferences 只找到 1 处：项目还没加载完

会话里第一次查引用，TypeScript 服务器往往只回答定义本身，这是一个已知问题，再查一次通常就对了；想让第一次就对，可以关掉 typescript-language-server 的语法服务器。2026 年 11 月 2 日的测试里，会话以读取 src/price.ts 开始，然后连续三轮对 priceWithTax 调用 findReferences。正确答案是 3 个文件里共 5 处，官方插件在 3 个会话里第一次调用都只返回 Found 1 reference: src/price.ts:1:17，三轮结果分别是 1、5、5，1、1、1，以及 1、1、5。

Scott Spence 在 2026 年 10 月 10 日的文章里给出了更大的样本和原因。他用 Claude Code 2.1.296 在自己的 SvelteKit 项目上跑无头会话，会话里第一次调用在最初 19 个会话中错了 18 次，之后计时的 13 个会话全错，重试后才正确。原因是 Claude Code 在服务器还没加载完项目时就发问，而 typescript-language-server 这时用一个轻量的语法服务器作答，它只认识被问到的那个文件；有人在 Python 语言服务器上也遇到同样的"先一处、后全部"，Claude Code 的仓库里有一个未关闭的 issue 在跟踪。

他的规避办法是在 TypeScript 服务器的配置里加上 initializationOptions，把 useSyntaxServer 设成 never。下面是 2026 年 11 月 2 日测试用的完整 .lsp.json，在官方配置上只多了最后一项：

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": { ".ts": "typescript", ".tsx": "typescriptreact", ".js": "javascript", ".jsx": "javascriptreact", ".mts": "typescript", ".cts": "typescript", ".mjs": "javascript", ".cjs": "javascript" },
    "initializationOptions": { "tsserver": { "useSyntaxServer": "never" } }
  }
}

把这段配置用上有两条路。一是直接改官方市场的清单文件 ~/.claude/plugins/marketplaces/claude-plugins-official/.claude-plugin/marketplace.json，在 lspServers 下找到 typescript，加上 initializationOptions 这一块；简单，但市场一更新就可能被覆盖。二是把它做成你自己的插件（目录结构见下一节），再运行 /plugin disable typescript-lsp@claude-plugins-official 禁用官方插件，因为两个插件认领同样的扩展名，只有先注册的那个会被使用。2026 年 11 月 2 日的测试走的是第二条路，用 --plugin-dir 加载本地插件、禁用官方插件，两个会话三轮都是 5 处。Scott 也把同样的配置打包进了他自己的市场 spences10/svelte-skills-kit，装第三方插件之前该怎么看它做了什么，见 Claude Code Mods 怎么用：安装前先审查，再写第一个 mod。

代价是第一次查询变慢。Scott 的项目上，第一次调用从约 0.5 秒（但结果是错的）变成约 2 秒，加载后的内存从约 935 MB、4 个进程降到约 725 MB、3 个进程；他提醒大项目的等待会长得多。这只是官方修复之前的权宜之计，修好后删掉自己的插件，运行 /plugin enable typescript-lsp@claude-plugins-official 换回官方插件。

没有官方插件的语言：自己写 .lsp.json

表里没有的语言，只要它有语言服务器，就能自己写一个插件接上：插件根目录放一个 .lsp.json，写明启动命令和它处理的扩展名，再用 --plugin-dir 加载或发布到市场。下面以 YAML 为例，步骤和 2026 年 11 月 2 日测试用的插件一致：

1. 新建插件目录，比如 yaml-lsp-local，在里面建 .claude-plugin/plugin.json，写上 name、version、description。
2. 在插件根目录建 .lsp.json，以服务器名为键写配置，外面不再套别的对象。command 只写程序名，参数放进 args；extensionToLanguage 的键要以点开头，至少一项。
3. 装好语言服务器程序本身，插件同样不带程序。
4. 运行 claude --debug --plugin-dir ./yaml-lsp-local 只在这一次会话里加载它，在调试日志里找 Loaded 1 LSP server(s) from plugin: yaml-lsp-local，或者看 /plugin 的 Errors 标签有没有报错。

{ "name": "yaml-lsp-local", "version": "0.1.0", "description": "yaml-language-server for .yaml/.yml" }

{
  "yaml": {
    "command": "yaml-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": { ".yaml": "yaml", ".yml": "yaml" }
  }
}

第一段是 plugin.json，第二段是 .lsp.json。别指望 claude plugin validate 帮你查 .lsp.json：测试里正确的文件能通过，写错键名（把 extensionToLanguage 写成 extensions）、command 里带空格、扩展名不带点这三种错误写法也都显示"Validation passed with warnings"，它根本不读这个文件。错误要到加载时才暴露，写错键名的那份在调试日志里报 LSP config validation failed for .lsp.json，原因是 unrecognized_keys，服务器没有加载；官方文档说这时整个文件都会被跳过，Errors 标签显示 Invalid LSP server config for ".lsp.json"。这组测试验证的是配置能否加载，测试机上没有装 yaml-language-server 本身。

可选字段按 Claude Code 插件参考里的 lspServers 字段表写，包括 env、initializationOptions、settings、workspaceFolder、startupTimeout、shutdownTimeout、requestTimeout（默认 60,000 毫秒，需要 2.1.288 及以上）、restartOnCrash、maxRestarts 和 diagnostics。配置是严格校验的，多写一个不认识的键就整份失败。两个启用的服务器认领同一个扩展名时，先注册的那个生效，Errors 标签会提示另一个没被使用。

在 VS Code 里用 Claude Code，还要装 LSP 插件吗

要。VS Code 里 Claude 能看到的报错来自另一套机制：按 Claude Code 的 VS Code 文档，接入 VS Code 扩展的终端版通过 mcp__ide__getDiagnostics 读取 VS Code"问题"面板里的错误和警告，聊天面板（2.1.285 及以上）通过内置的 claude-vscode 服务器读取同一个面板。读到的是编辑器自己的语言服务器的结果，而且是 Claude 主动去读才有，不是每次改完文件自动送来，也没有 LSP 导航工具。

从文档的描述看，在 VS Code 里想要改完自动推送的诊断和按符号导航，仍然要装代码智能插件，语言服务器程序也照样要装；安装用 VS Code 扩展自己的插件界面，不用第 2 步的斜杠命令。只想让 Claude 偶尔看一眼编辑器里的报错，不装也行。

LSP 吃内存吗：rust-analyzer 和 pyright 会索引整个项目

会，尤其是大项目。官方排错文档点名 rust-analyzer 和 pyright 会索引整个项目，内存在索引过程中持续上涨；觉得占用太多，就在会话里运行 /plugin disable rust-analyzer-lsp@claude-plugins-official 这类命令关掉对应插件，让 Claude 回到内置的搜索工具，诊断和导航随之没有。小一些的参考是 Scott Spence 的 TypeScript 项目，服务器加载后约 935 MB、4 个进程。

Linux 和 WSL 上还有一处要留意：设了 CLAUDE_CODE_TOOL_MEMORY_LIMIT 给工具进程封顶后，Claude Code 可能把语言服务器也算进这个上限，进程超限被内核杀掉时结果里不会写原因。不想让语言服务器受限，把 CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE 设成 lsp（需要 2.1.246 及以上）。

装了 LSP，Claude 还是用 grep 搜代码吗

经常是。LSP 工具要 Claude 自己决定去调，没有明确要求时它多半照旧用 grep。Scott Spence 翻了自己 2 月底到 4 月的约 650 个会话，只有 15 个会话里出现过 LSP 调用，一共 32 次；在 CLAUDE.md 里写明"查定义和引用用 LSP"之后，12 个关于符号的提问全部用了 LSP，去掉这条规则只有大约一半。

不过他后来的对比测试发现，查"某个函数在哪里被用到"时只用 grep 一次都没答错，还最快、最省；LSP 的长处在 hover 一次就能给出准确类型。他现在的规则改成了查引用用 grep、查类型用 hover，并且不把 findReferences 的结果当完整列表。他还发现，从 shell 改动的文件（比如用 Bash 往服务器已经打开的文件里追加内容）服务器看不到，只有 Claude 用自己的编辑工具改的文件才会同步过去。所以 LSP 最稳的收益是改完自动送来的诊断，导航工具用不用、怎么用，取决于你给 Claude 写的规则。规则写在 CLAUDE.md 还是做成 skill，见 Claude Code Hooks、Skills 与斜杠命令：区别、选型和最小配置。

Claude Code LSP 配置的其他问题

Claude Code 从哪个版本开始支持 LSP？

按官方 changelog，LSP 工具在 2.0.74（2025 年 12 月 19 日）加入；配置字段 requestTimeout 需要 2.1.288（2026 年 10 月 2 日）及以上。截至 2026 年 11 月 2 日的最新版本是 2.1.316（10 月 31 日发布），旧教程里的"2.0.74 或更高"只是最低门槛，用当前版本即可。

Windows 上能用 Claude Code LSP 吗？

能，官方文档的确认步骤里也给了 PowerShell 的 Get-Command typescript-language-server。早期版本在 Windows 上因为文件路径格式错误而失效，2.1.74（2026 年 3 月 12 日）已修复；C/C++ 的 clangd 可以用 winget install LLVM.LLVM 安装。

一个项目里有多种语言，可以同时装几个 LSP 插件吗？

可以，每种语言装各自的插件和程序，Claude 编辑哪种扩展名的文件就启动对应的服务器。限制是一个扩展名只由一个服务器处理，两个插件认领同一个扩展名时只有先注册的生效。

只想要导航、不想让诊断进对话，能关掉诊断吗？

官方插件没有这个开关，自己写插件时可以：.lsp.json 里的 diagnostics 字段默认是 true，设成 false 后服务器照常提供导航，但改完文件不再把诊断推进对话。