Claude Code LSP 在 Windows 上的配置与排坑

背景

Claude Code 从 v2.0.74 开始支持 LSP（Language Server Protocol），提供 documentSymbol、goToDefinition、findReferences、hover 等代码智能功能。本文记录我在 Windows 上配置 Python、Kotlin、Java、TypeScript 四个语言服务器的完整过程与踩坑经验。

环境

Windows 11 + Git Bash
Claude Code（使用 uv_spawn 启动 LSP 进程）
Node.js v24

第一步：启用 LSP 功能

LSP 是实验性功能，需要在 settings.local.json 中开启：

json 复制代码

{
  "env": {
    "ENABLE_LSP_TOOL": "1"
  }
}

重启 Claude Code 后，/plugin install pyright-lsp 等命令才能正常加载语言服务器插件。

第二步：Python（pyright）------ 顺利

bash 复制代码

uv tool install pyright

重启后 LSP 正常工作。pyright-lsp 是 Python 包，通过 uv tool install 安装后会在 ~/.local/bin/ 生成 pyright-langserver.exe shim，uv_spawn 能直接找到并启动。

第三步：Kotlin ------ 踩坑开始

尝试一：照搬 Python 方案

bash 复制代码

uv tool install kotlin-lsp   # 失败：不是 Python 包

尝试二：用 brew 安装

bash 复制代码

brew install kotlin-lsp

安装成功，~/bin/kotlin-lsp 和 ~/bin/kotlin-lsp.cmd 都存在，但 LSP 报错：

perl 复制代码

ENOENT: no such file or directory, uv_spawn 'kotlin-lsp'

尝试三：排查 PATH 问题

Git Bash 下 kotlin-lsp --help 正常执行
which kotlin-lsp 返回 /c/Users/wuchaoli/bin/kotlin-lsp
Windows 系统 PATH 不包含 ~/bin（Git Bash 的 PATH 和 Windows 系统 PATH 是独立的）

尝试四：把 wrapper 放入插件 bin 目录

在插件缓存 ~/.claude/plugins/cache/claude-plugins-official/kotlin-lsp/1.0.0/bin/ 创建 kotlin-lsp.cmd wrapper，指向真实 exe。

结果：仍然 ENOENT。

关键发现

用 Node.js 直接测试：

js 复制代码

const { spawn } = require('child_process');
spawn('kotlin-lsp.cmd', ['--help']);  // EINVAL!

Windows 上 child_process.spawn() 无法直接启动 .cmd / .bat 文件 ，必须使用 shell: true 或通过 cmd.exe /c 包装。这是 Node.js 的已知限制。

而 uv_spawn（Claude Code 内部的 libuv spawn 封装）不会使用 shell: true，因此 .cmd wrapper 无论放在哪里都无法被启动。

最终方案：`.exe` 符号链接

JetBrains 提供的 Kotlin LSP 服务器包中自带真正的 .exe 入口：bin/intellij-server.exe。在 ~/.local/bin/ 创建符号链接指向它：

powershell 复制代码

New-Item -ItemType SymbolicLink `
  -Path 'C:\Users\<user>\.local\bin\kotlin-lsp.exe' `
  -Target 'C:\Users\<user>\.local\share\kotlin-lsp\bin\intellij-server.exe'

uv_spawn('kotlin-lsp') → Windows 自动补全 .exe → 找到 kotlin-lsp.exe → 符号链接跳转到真实的 exe → 启动成功。

总结：LSP 在 Windows 上的通用排坑公式

javascript 复制代码

uv_spawn 能启动的 = 只有 .exe（不能是 .cmd / .bat / shell 脚本）
uv_spawn 搜索路径 = uv 工具路径（~/.local/bin/）+ 系统 PATH

语言	LSP 包	安装方式	Windows 适配方案
Python	pyright	`uv tool install pyright`	直接可用（uv 自动生成 .exe shim）
Kotlin	kotlin-lsp	下载 JetBrains 官方 zip	创建 `kotlin-lsp.exe` 符号链接指向真实 exe
Java	jdtls	`uv tool install karellen-jdtls`	待验证（同上思路）
TypeScript	typescript-language-server	`npm install -g`	待验证（需检查 npm 是否生成 .exe shim）

核心教训

不要用 .cmd / .bat / bash 脚本作为 LSP 入口 --- uv_spawn 无法启动它们
~/.local/bin/ 是 uv 生态的关键路径 --- 把 .exe 入口放在这里
uv tool install 只适用于 Python 包 --- JVM / Node.js 的 LSP 需要找到对应的真正 .exe
Git Bash PATH ≠ Windows 系统 PATH --- Node.js 进程使用系统 PATH，不经过 Git Bash 的路径转换
Claude Code 的 LSP 插件是"薄包装" --- 只声明配置（命令名、参数、扩展名映射），语言服务器本体需要自己安装

Claude Code LSP 在 Windows 上的配置与排坑