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

> 截至 2026 年 11 月，Claude Code 的 LSP 靠代码智能插件加自己装的语言服务器，无需开关变量；装了没反应，多半是官方市场没注册、程序不在 PATH 或缺依赖。

- URL: https://blog.laozhang.ai/zh/posts/claude-code-lsp
- Published: 2026-11-02
- Updated: 2026-11-02
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: Claude Code
- Tags: Claude Code, LSP, 语言服务器, 插件, AI 编程

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

LSP 和 MCP 不是一回事：LSP 只服务于本地代码的类型和符号，MCP 接的是外部服务和数据。想挑 MCP，看 [Claude Code 最值得先加的 MCP（2026）：按工作流选第一批集成](https://blog.laozhang.ai/zh/posts/claude-code-best-mcp-servers)。

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

顺序是先程序、后插件、再确认，官方文档也按这个顺序写。还没装 Claude Code 本身的，先看 [Claude Code 安装教程：全平台完整设置指南（2026）](https://blog.laozhang.ai/zh/posts/claude-code-install)。

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 成本：一次对话为什么突然变贵](https://blog.laozhang.ai/zh/posts/claude-code-cache-miss-token-costs)。

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

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

| 语言 | 插件名 | 语言服务器程序 | 安装程序的命令 |
| --- | --- | --- | --- |
| TypeScript / JavaScript | `typescript-lsp` | `typescript-language-server` | `npm install -g typescript-language-server typescript` |
| Python | `pyright-lsp` | `pyright-langserver` | `npm install -g pyright`，或 `pip install pyright`、`pipx install pyright` |
| Go | `gopls-lsp` | `gopls` | `go install golang.org/x/tools/gopls@latest` |
| Rust | `rust-analyzer-lsp` | `rust-analyzer` | `rustup component add rust-analyzer`，也可用 brew、apt、pacman 安装 |
| Java | `jdtls-lsp` | `jdtls` | `brew install jdtls`，需要 Java 17 以上的 JDK；Linux 多为手动安装，再把 `jdtls` 启动脚本放进 PATH |
| C / C++ | `clangd-lsp` | `clangd` | `brew install llvm`、`sudo apt install clangd` 或 `winget install LLVM.LLVM` |
| C# | `csharp-lsp` | `csharp-ls` | `dotnet tool install --global csharp-ls`，需要 .NET SDK 6.0 以上 |
| Kotlin | `kotlin-lsp` | `kotlin-lsp` | `brew install JetBrains/utils/kotlin-lsp` |
| Lua | `lua-lsp` | `lua-language-server` | `brew install lua-language-server`，也有 snap、pacman、dnf 包 |
| PHP | `php-lsp` | `intelephense` | `npm install -g intelephense` |
| Ruby | `ruby-lsp` | `ruby-lsp` | `gem install ruby-lsp` |
| Swift | `swift-lsp` | `sourcekit-lsp` | 随 Swift 工具链提供：装 Xcode 或 `brew install swift`，Linux 从 swift.org 安装 |
| Liquid | `liquid-lsp` | `shopify` | 安装 Shopify CLI，见 [Shopify 的 liquid-lsp 插件说明](https://github.com/Shopify/liquid-skills/tree/main/plugins/liquid-lsp) |

除了 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** 能展开看具体是哪些错误。

![终端里诊断提示行出现在写入文件之后的下一个工具行下面，Claude 在下一个请求里才收到 new-diagnostics 诊断](https://blog.laozhang.ai/posts/zh/claude-code-lsp/img/lsp-diagnostics-next-turn.webp)

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 秒后报出错误；这个错误没有出现在写入工具的结果里，而是附在下一个请求里，原文如下：

```text
<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 的文章](https://scottspence.com/posts/revisiting-lsp-in-claude-code)里记录，在两个很短、编辑就是最后一步的会话里，类型错误一直没有报出来；在较长的会话里，错误约 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` 显示插件已装在用户范围、处于启用状态。

| 选项 | 结果 | 之后想改回来 |
| --- | --- | --- |
| Yes, install（安装） | 为你的用户账户装上插件，提示 `installed · restart to apply`，开新会话才加载服务器 | 用 `/plugin disable` 或 `/plugin uninstall` 加插件全名 |
| No, not now（暂不），或按 Esc | 关闭弹窗，以后的会话还会再推荐 | 不用改 |
| Never for this plugin（不再推荐这个插件） | 这个插件不再弹，其他语言照常推荐 | 从 `~/.claude.json` 的 `lspRecommendationNeverPlugins` 列表里删掉 `typescript-lsp@claude-plugins-official` 这类全名 |
| Disable all LSP recommendations（关闭全部推荐） | 所有语言都不再弹 | 从 `~/.claude.json` 删掉 `lspRecommendationDisabled` 和 `lspRecommendationIgnoredCount` 两个键 |

弹窗 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 教程](https://karanbansal.in/blog/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 插件排错文档](https://code.claude.com/docs/en/plugins/troubleshooting)还写明，`claude plugin` 这组系统终端命令从不替你注册它。

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

```text
✘ 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`，因为根本没有这个市场可以更新。真正修好的是先添加市场，再装插件：

```bash
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` 启动后看调试日志。

![Claude Code LSP 装了没反应的五种症状、对应报错原文和修复办法对照图](https://blog.laozhang.ai/posts/zh/claude-code-lsp/img/lsp-no-response-fixes.webp)

| 症状 | 在哪里看到 | 原因 | 解决办法 |
| --- | --- | --- | --- |
| 改了文件，始终没有诊断提示行 | `/plugin` 的 Errors 标签显示 `Executable not found in $PATH: "typescript-language-server"`；调试日志有 `failed to start` | 程序没装，或不在启动 `claude` 的那个终端的 PATH 上 | 装好程序并用 `which` 确认，从能找到它的终端开新会话 |
| TypeScript 项目没有诊断，程序明明装了 | 调试日志：`Could not find a valid TypeScript installation` | 项目里没有 `typescript` 包，服务器初始化时直接退出 | 在项目里运行 `npm install -D typescript`，或按 README 全局安装 `typescript` |
| 导航调用返回 `server is starting` | LSP 工具的返回结果 | 第一次编辑后服务器刚启动，还没就绪 | 等几秒再问；Java、Kotlin 服务器启动更慢 |
| `findReferences` 只返回定义本身 | 返回 `Found 1 reference` | 会话里第一次查询时项目还没加载完 | 再查一次，或用下一节的配置 |
| `No LSP server available for file type: .md` | LSP 工具的返回结果 | 这个扩展名没有任何插件负责 | 装对应语言的插件，或自己写 `.lsp.json` |
| monorepo 里一堆 import 被报"无法解析" | 诊断内容 | 语言服务器没有按这个工作区配置 | Claude Code 这边无须改动，诊断也不会阻止 Claude 编辑；按该语言服务器的工作区设置处理 |
| 插件装了，却既没有 `LSP` 工具也没有诊断 | `/plugin` 的已安装列表或 `claude plugin list` 显示 disabled；或刚在弹窗里选了 Yes, install | 插件被禁用，或装完还没重启 | 运行 `/plugin enable typescript-lsp@claude-plugins-official`（系统终端里用 `claude plugin enable` 加同样的全名），然后开新会话 |
| 网页版或 `claude --cloud` 里完全没有 LSP | 云端会话 | 云端会话不启动插件的语言服务器 | 改在本地终端会话里用 |
| 排查时一切插件都没加载 | 用了 `--safe-mode`、`CLAUDE_CODE_SAFE_MODE=1`，或脚本里的 `claude -p --bare` | 这些模式本来就跳过语言服务器 | 正常启动 `claude` |

表里第一、二行的调试日志原文来自 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、本地控制和第三方界面](https://blog.laozhang.ai/zh/posts/claude-code-web-interface)。

## 首次 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 日的文章](https://scottspence.com/posts/revisiting-lsp-in-claude-code)里给出了更大的样本和原因。他用 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`，在官方配置上只多了最后一项：

```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](https://blog.laozhang.ai/zh/posts/claude-code-mods)。

代价是第一次查询变慢。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 标签有没有报错。

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

```json
{
  "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 字段表](https://code.claude.com/docs/en/plugins-reference#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 文档](https://code.claude.com/docs/en/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 与斜杠命令：区别、选型和最小配置](https://blog.laozhang.ai/zh/posts/claude-code-hooks-slash-commands-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` 后服务器照常提供导航，但改完文件不再把诊断推进对话。

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-11-02。

- [Claude Code 代码智能插件文档](https://code.claude.com/docs/en/plugins/code-intelligence) (code.claude.com)
- [Shopify 的 liquid-lsp 插件说明](https://github.com/Shopify/liquid-skills/tree/main/plugins/liquid-lsp) (github.com)
- [2026 年 10 月 10 日重新测试 Claude Code LSP 的文章](https://scottspence.com/posts/revisiting-lsp-in-claude-code) (scottspence.com)
- [karanbansal.in 2026 年 2 月 28 日的 Claude Code LSP 教程](https://karanbansal.in/blog/claude-code-lsp/) (karanbansal.in)
- [Claude Code 插件排错文档](https://code.claude.com/docs/en/plugins/troubleshooting) (code.claude.com)
- [Claude Code 插件参考里的 lspServers 字段表](https://code.claude.com/docs/en/plugins-reference) (code.claude.com)
- [Claude Code 的 VS Code 文档](https://code.claude.com/docs/en/vs-code) (code.claude.com)