【学习笔记】Claude Code LSP 详解

学习笔记系列 · 第六篇

本篇深入讲解 Claude Code 中的 LSP（Language Server Protocol）集成：配置方式、支持的语言、Claude 获得的能力和创建自定义 LSP 插件。

1. LSP 是什么

LSP（Language Server Protocol）是 IDE 和语言服务器之间的标准通信协议。VS Code 的代码智能（跳转定义、查找引用、错误提示）就是通过 LSP 实现的。

Claude Code 从 2.0.74 版本开始正式支持 LSP，让 Claude 也能获得类似 IDE 的代码智能能力。

传统方式：
  Claude 用 Grep 搜索 → 可能遗漏、精确度低

LSP 方式：
  Claude 调用 LSP 工具 → 精确跳转到定义、查找所有引用

2. Claude 通过 LSP 获得什么

安装 LSP 插件后，Claude 获得两个核心能力：

2.1 自动诊断

每次 Claude 编辑文件后，语言服务器会自动分析变更并报告错误和警告：

• 类型错误
• 缺失的导入
• 语法问题
• 未使用的变量

Claude 看到诊断结果后可以在同一轮对话中修复问题，无需运行编译器或 linter。

查看方式：按 Ctrl+O 当出现 “diagnostics found” 指示器时。

2.2 代码导航

Claude 可以使用 LSP 进行精确的代码导航：

• 跳转到定义（goToDefinition）
• 跳转到实现（goToImplementation）
• 悬停查看类型（hover）
• 列出文件符号（documentSymbol）
• 查找所有引用（findReferences）
• 搜索工作区符号（workspaceSymbol）
• 调用层次（prepareCallHierarchy、incomingCalls、outgoingCalls）

这些操作比 Grep 搜索更精确，因为它们基于语言的语义理解。

3. .lsp.json 文件格式

基本结构

{
  "language-id": {
    "command": "lsp-server-command",
    "extensionToLanguage": {
      ".ext": "language-id"
    }
  }
}

字段说明

必需字段

可选字段

示例

Go 语言

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Python（Pyright）

{
  "python": {
    "command": "pyright-langserver",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".py": "python",
      ".pyi": "python"
    },
    "settings": {
      "python": {
        "analysis": {
          "typeCheckingMode": "basic"
        }
      }
    }
  }
}

TypeScript

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact",
      ".js": "javascript",
      ".jsx": "javascriptreact"
    }
  }
}

4. 配置方式

4.1 从 Marketplace 安装（推荐）

最简单的方式是从官方 Marketplace 安装已有的 LSP 插件：

/plugin

在 Discover 标签中搜索 “lsp”，找到对应语言的插件安装。

4.2 临时或自定义配置

官方推荐通过插件提供 .lsp.json 或在 plugin.json 中内联 lspServers。如果只是临时验证某个语言服务器，建议创建一个最小 LSP 插件，而不是把 LSP 配置直接塞进普通 settings；普通 plugin settings.json 当前也只支持少量默认设置，不适合承载 LSP server 定义。

4.3 创建自定义 LSP 插件

为没有官方插件的语言创建 LSP 插件（见下一节）。

5. 已有 LSP 插件

社区和官方提供了多种 LSP 插件：

官方 marketplace 和社区插件会持续变化。安装前以 /plugin 的 Discover 搜索结果为准；上表只列官方参考文档中明确提到的代表性插件。

安装步骤：

1. 先安装语言服务器的二进制文件
2. 从 Marketplace 安装对应的 LSP 插件
3. 重启 Claude Code

6. 创建自定义 LSP 插件

插件结构

my-lsp-plugin/
├── .claude-plugin/
│   └── plugin.json
├── .lsp.json
└── hooks/
    ├── hooks.json
    └── check-my-lsp.sh

plugin.json

{
  "name": "my-language-lsp",
  "displayName": "My Language LSP",
  "description": "LSP support for My Language",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "license": "MIT"
}

.lsp.json

{
  "my-language": {
    "command": "my-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".myext": "my-language"
    },
    "startupTimeout": 10000,
    "maxRestarts": 3
  }
}

7. 插件中的 LSP

独立 .lsp.json（推荐）

在插件根目录创建 .lsp.json：

{
  "go": {
    "command": "gopls",
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

内联在 plugin.json 中

{
  "name": "gopls-lsp",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

plugin.json 中的 lspServers 路径

{
  "name": "my-plugin",
  "lspServers": "./.lsp.json"
}

8. LSP 工具操作

Claude Code 内置了 LSP 工具，有 9 种操作：

可用性取决于具体语言的 LSP server 实现。

9. 调试与常见问题

9.1 查看 LSP 状态

/plugin

在 Errors 标签中查看 LSP 相关错误。

9.2 常见问题

9.3 安装二进制文件示例

# Python
pip install pyright
# 或
npm install -g pyright

# TypeScript
npm install -g typescript-language-server typescript

# Go
go install golang.org/x/tools/gopls@latest

# Rust
rustup component add rust-analyzer

10. 最佳实践

10.1 先安装二进制，再安装插件

LSP 插件只配置如何连接，不包含语言服务器本身。

10.2 大项目注意内存

rust-analyzer 和 pyright 在大型项目上可能消耗大量内存。如果遇到内存问题，禁用插件。

10.3 利用自动诊断

LSP 最大的价值是自动诊断——Claude 编辑文件后立即看到错误。这比手动运行编译器快得多。

10.4 不要过度依赖

LSP 是补充工具，不是替代。对于简单的文本搜索，Grep 已经足够。LSP 的优势在语义级别操作。

11. 本项目实例

GLM StatusLine 插件没有使用 LSP。插件是用 JavaScript/Node.js 编写的单文件脚本，Claude Code 内置的 Read、Grep、Glob 工具已经足够分析和编辑这个项目。

如果项目变大（比如拆分成多个模块），可以考虑安装 TypeScript LSP 插件来获得更好的代码智能。

参考资料

• Claude Code 官方文档 - Plugins reference
• Claude Code 官方文档 - Discover and install prebuilt plugins
• Claude Code LSP 插件集合（boostvolt）
• Claude Code LSP 插件集合（Piebald-AI）
• Language Server Protocol 规范

系列导航

📌 本文相关仓库：BingqiangZhou/CCStatusline — Claude Code 插件系统学习笔记 & GLM StatusLine 实践案例