using-typescript-lsp

使用 TypeScript LSP

概述

typescript-lsp 插件为 TypeScript 和 JavaScript 提供语义代码智能。需要确保语义准确时，请使用 LSP 工具，而不是 grep/read——LSP 能理解 TypeScript 的类型系统、继承、接口和符号关系。

何时使用 LSP，何时使用文本搜索

digraph lsp_decision {
    "Need code info?" [shape=diamond];
    "Semantic accuracy needed?" [shape=diamond];
    "Use LSP tool" [shape=box];
    "Use Grep/Read" [shape=box];

    "Need code info?" -> "Semantic accuracy needed?" [label="yes"];
    "Need code info?" -> "Use Grep/Read" [label="no - text patterns"];
    "Semantic accuracy needed?" -> "Use LSP tool" [label="yes"];
    "Semantic accuracy needed?" -> "Use Grep/Read" [label="no"];
}

适合使用 LSP 的场景：

• 重构前查找所有用法
• 获取类型信息（推断类型或显式类型）
• 跳转到定义处（包括 node_modules）
• 检查类型错误
• 了解接口的实现情况

适合使用 Grep 的场景：

• 搜索文本模式（注释、字符串、配置文件）
• 跨语言搜索
• JSON、YAML、markdown 内容
• LSP 不可用时

LSP 操作速查表

任务	LSP 操作	替代方式
查找函数的所有调用处	findReferences	搜索函数名
获取函数／变量的类型	hover	读取文件并解析
跳转到定义处	goToDefinition	Grep + Read
检查类型错误	getDiagnostics	运行 tsc CLI
查看文件结构	documentSymbol	读取整个文件

关键模式

重构前：查找所有引用

错误做法：

Grep for "formatDuration" -> may miss renamed imports, get false positives from comments

正确做法：

LSP findReferences on symbol -> gets ALL semantic usages, no false positives

获取类型信息

错误做法：

Read file -> find function -> manually trace type inference

正确做法：

LSP hover on symbol -> instant type signature with inferred types resolved

验证类型正确性

错误做法：

Bash: npx tsc --noEmit (slow, external process)

正确做法：

LSP getDiagnostics on changed files -> instant, no subprocess

查找接口实现

错误做法：

Grep for "implements InterfaceName" -> misses duck-typed objects

正确做法：

LSP findReferences on interface -> finds all implementations including structural matches

常见错误

错误	错误原因	修正方法
重命名前用 Grep 搜索符号	文本搜索会漏掉别名导入和重新导出	使用 findReferences
为了查一个类型而读取整个文件	浪费上下文，速度慢	使用 hover
每次更改后都运行 tsc	速度慢，还需使用外部工具	使用 getDiagnostics
用 Grep 查找定义	可能找到错误匹配项（同名但属于不同模块）	使用 goToDefinition
用 Grep 搜索接口用法	会漏掉结构化类型或鸭子类型	使用 findReferences

LSP 工具的工作方式

LSP 是 Claude Code 内置工具，不是 bash 命令。启用 typescript-lsp 插件后，Claude Code 会自动提供以下操作：

• goToDefinition - 跳转到符号定义处
• findReferences - 查找符号的所有用法
• hover - 获取类型签名和文档
• getDiagnostics - 获取文件的类型错误
• documentSymbol - 列出文件中的所有符号

这些操作通过 Claude 的工具系统调用，而不是通过 bash。 如果 LSP 不可用，请改用 grep/read，但要说明这一限制。

支持的文件类型

.ts、.tsx、.js、.jsx、.mts、.cts、.mjs、.cjs

先决条件

1. 已启用插件： ~/.claude/settings.json 中包含 typescript-lsp@claude-plugins-official
2. 已安装语言服务器： npm install -g typescript-language-server typescript
3. 已配置项目： 存在 tsconfig.json 或 jsconfig.json（建议配置，以提高准确性）

检查 LSP 是否可用

始终优先尝试使用 LSP。 如果 LSP 工具不可用，它们会返回错误。不要仅仅因为不确定就提前改用 grep。

1. Attempt LSP operation (e.g., findReferences)
2. If tool error → fall back to grep/read with documented limitation
3. If success → use the semantic results

后备方案

如果 LSP 不可用（未找到工具或服务器未运行）：

1. 说明限制 - 明确指出：“LSP 不可用，改用文本搜索作为后备方案”
2. 谨慎使用 Grep - 注意它可能会漏掉别名导入或重新导出
3. 手动验证 - 对于重构，仔细检查结果在语义上是否合理
4. 建议修复 - 提醒用户确保已安装 typescript-language-server 并启用插件

绝不要悄悄改用后备方案。 使用文本搜索而不是 LSP 时，务必告知用户，让他们了解其中的限制。

警示信号——停止并使用 LSP

如果出现以下想法，说明你应该使用 LSP，而不是 grep：

想法	实际情况
“让我 grep 一下这个函数”	如果它是一个符号，请使用 findReferences
“我来读一下文件，找出类型”	使用 hover 即可即时获取类型信息
“我来运行 tsc 检查”	使用 getDiagnostics——速度更快，无需启动子进程
“我来搜索一下它的定义位置”	使用 goToDefinition——语义准确性更高
“快速搜索的话，Grep 更快”	LSP 执行语义查询更快
“我需要找出所有实现”	使用 findReferences——还能捕获结构性匹配

LSP 无法提供帮助的情况

• 未安装 typescript-language-server 二进制文件
• 使用不带 jsconfig.json 的纯 JavaScript（类型推断能力有限）
• 跨语言引用（例如，TypeScript 通过 WASM 调用 Rust）
• 搜索注释或字符串字面量
• 配置文件（JSON、YAML 等）
• 尚未安装 Node 模块（需先运行 npm install）