幫 Claude Code 裝上 LSP：從文字搜尋升級到語意導航

Claude Code

AI 文章延伸

AI 幫你讀這篇文章

選擇平台後可直接帶入閱讀脈絡，快速整理重點、補齊盲點，並延伸到同站相關文章。

讓 ChatGPT 幫你讀 讓 Google 幫你讀

我們團隊日常開發都用 Claude Code 作為 AI 程式助手。一般情況下它靠 Grep 和 Glob 搜尋檔案，對小專案來說夠用，但專案一大，每次找定義或追引用都要翻好幾輪文字搜尋，效率明顯下降。

後來發現 Claude Code 從 v2.0.74 開始支援 LSP（Language Server Protocol），裝上之後它就像拿到了 IDE 的「程式碼地圖」——跳轉定義、查引用、看型別，都是毫秒級回應。根據社群的測試數據，查詢速度從原本的 45 秒降到 50ms，快了將近 900 倍。

這篇整理我們實際安裝的過程，涵蓋 TypeScript / JavaScript、Python、PHP 三種我們最常用的語言。

LSP 是什麼？為什麼 Claude Code 需要它？

LSP 是微軟提出的通訊協定，讓編輯器和語言伺服器之間有統一的溝通方式。VS Code、Neovim 這些編輯器的「跳轉定義」「查找引用」功能，背後都是 LSP 在運作。

沒有 LSP 的 Claude Code 只能靠文字比對來理解程式碼。問它「這個函式定義在哪」，它得用 Grep 掃一遍檔案，碰到同名變數或字串就容易搞混。裝上 LSP 之後，它能直接跟語言伺服器溝通，拿到精確的型別資訊和符號位置。

裝完 LSP 後 Claude Code 會多出一個 LSP 工具，支援以下操作：

  • goToDefinition — 跳轉到符號定義
  • findReferences — 查找所有引用
  • hover — 取得型別資訊和文件說明
  • documentSymbol — 列出檔案中的所有符號
  • workspaceSymbol — 跨檔案搜尋符號

安裝前的準備

Claude Code 的 LSP 透過 Plugin 系統運作。安裝流程分兩步：先在系統上裝好語言伺服器的執行檔，再透過 Claude Code 的 /plugin 指令從官方市集 claude-plugins-official 安裝對應的 Plugin。

確認你的 Claude Code 版本在 v2.0.74 以上：

claude --version

TypeScript / JavaScript

TypeScript 用的是 vtsls（Vue/TypeScript Language Server），支援 .ts、.tsx、.js、.jsx、.mts、.cts 等副檔名。

安裝語言伺服器

npm install -g @vtsls/language-server typescript

用 pnpm 或 bun 也可以：

# pnpm
pnpm install -g @vtsls/language-server typescript

# bun
bun install -g @vtsls/language-server typescript

安裝 Claude Code Plugin

在 Claude Code 中輸入：

/plugin install typescript-lsp@claude-plugins-official

重啟 Claude Code 讓 LSP 伺服器生效。

Python

Python 用的是 Pyright，微軟開發的高效能靜態型別檢查器。

安裝語言伺服器

npm install -g pyright

安裝 Claude Code Plugin

/plugin install pyright@claude-plugins-official

重啟 Claude Code。

PHP

PHP 用的是 Intelephense，高效能的 PHP 語言伺服器，支援程式碼補全、定義跳轉、引用查找和即時診斷。

安裝語言伺服器

npm install -g intelephense

安裝 Claude Code Plugin

/plugin install php-lsp@claude-plugins-official

重啟 Claude Code。

驗證 LSP 是否正常運作

裝完之後怎麼確認有沒有成功？兩個步驟。

檢查 Plugin 狀態

在 Claude Code 中輸入 /plugin，切到 Installed 頁籤，確認你安裝的 Plugin 顯示 Status: enabled。

這是最常見的坑——Plugin 裝了但沒有啟用。如果狀態顯示 disabled，手動啟用：

claude plugin enable typescript-lsp

實際測試 LSP 工具

請 Claude Code 對一個具體的檔案執行 LSP 操作。例如在 TypeScript 專案中：

幫我用 LSP 的 hover 看一下 src/i18n/translations.ts 第 527 行第 14 個字元的型別資訊

如果 LSP 正常運作，你會看到回傳的型別定義，而不是「No LSP server available」的錯誤訊息。

也可以試試 documentSymbol，請 Claude Code 列出某個檔案的所有符號：

用 LSP 列出 src/i18n/translations.ts 的所有符號

正常的話會看到檔案中所有變數、函式、屬性的清單和行號。

常見問題排查

「No LSP server available」

最常見的原因有三個：

  1. 語言伺服器沒裝好 — 用 which vtsls、which pyright、which intelephense 確認執行檔在 PATH 中
  2. Plugin 沒啟用 — /plugin 檢查狀態，手動 enable
  3. 沒重啟 — LSP 伺服器需要在 Claude Code 啟動時載入，裝完 Plugin 後一定要重啟

環境變數 ENABLE_LSP_TOOL

部分版本的 Claude Code 需要手動啟用 LSP 工具。如果重啟後還是看不到 LSP 工具，在 ~/.zshrc 加上：

export ENABLE_LSP_TOOL=1

或是啟動時直接帶：

ENABLE_LSP_TOOL=1 claude

Plugin Errors 頁籤

/plugin 介面有個 Errors 頁籤，如果 LSP 伺服器啟動失敗，錯誤訊息會顯示在這裡。常見的錯誤是「Executable not found in $PATH」，代表語言伺服器的執行檔沒裝好或路徑不對。

實際開發中會觸發 LSP 的場景

裝上 LSP 之後，不需要特別下指令叫 Claude Code 去用它。在日常對話中描述需求，它會自己判斷該不該呼叫 LSP。以下是我們實際遇過的幾種情境。

改名重構：改一個變數，所有引用一起改

「幫我把 menuData 這個變數改名成 navigationData，所有引用的地方都要改到。」

沒有 LSP 的時候，Claude Code 會用 Grep 搜 menuData，但可能漏掉解構賦值的寫法，或是誤改到註解裡剛好出現的同名字串。有了 LSP，它會先用 findReferences 拿到所有真正引用到這個變數的位置，再逐一修改。

追蹤函式定義：這個函式到底在哪裡定義的？

「sanitize_text_field 這個函式是 WordPress 內建的還是我們自己寫的？幫我找到它的定義。」

Claude Code 會用 goToDefinition 跳到函式定義的位置。如果是專案內的函式，直接跳過去；如果是第三方套件或框架內建的，LSP 也會指向 node_modules 或 vendor 裡的原始碼。比起 Grep 搜出一堆 sanitize_text_field 的呼叫處，精確太多。

理解型別：這個參數到底接受什麼？

「getCollection 的回傳值是什麼型別？」

Claude Code 用 hover 查詢，直接拿到完整的型別簽名。在 TypeScript 專案裡特別有用——泛型嵌套幾層之後，光讀原始碼很難直接看出展開後的型別。LSP 會幫你把推導結果算好。

檢查誰在用這個 API：改動前的影響範圍評估

「我想改 CategoryNavigation 元件的 props 介面，幫我看看哪些地方有用到這個元件。」

findReferences 會列出所有引入和使用這個元件的檔案與行號。這比 Grep 搜元件名稱可靠，因為 Grep 會把 import 語句、註解、字串裡的提及全部撈出來，LSP 只回傳真正的程式碼引用。

掌握檔案結構：這個檔案裡有哪些函式和變數？

「列出 src/i18n/utils.ts 裡面所有 export 的函式。」

Claude Code 用 documentSymbol 取得檔案的完整符號清單，包含函式、變數、介面、型別別名，附帶行號。在閱讀不熟悉的程式碼時，這比從頭讀到尾快很多。

跨檔案搜尋：專案裡有沒有某個 class 或 function？

「專案裡有沒有叫 Pagination 的元件或型別？」

workspaceSymbol 會在整個專案範圍內搜尋符號名稱。跟 Glob 搜檔名不同，它搜的是程式碼裡的符號定義——同一個檔案裡定義了多個 class 或 function，它都能找到。

WordPress / PHP 開發：Hook 和 Filter 的追蹤

「woocommerce_checkout_order_processed 這個 action hook 在我們的外掛裡哪些地方有掛載？」

PHP 專案裝了 Intelephense 之後，findReferences 能精確找到 add_action 和 add_filter 中引用到的 hook 名稱，不會像純文字搜尋那樣把 do_action 的觸發點和 add_action 的掛載點混在一起。

重點整理

這些場景有個共通點：你不需要跟 Claude Code 說「請用 LSP」。正常描述你的需求，它會根據任務性質自動選擇用 Grep 還是 LSP。型別查詢、定義跳轉、引用追蹤這類需要語意理解的操作，它會優先走 LSP；純文字內容搜尋（例如找某段中文翻譯），它還是會用 Grep。

裝完 LSP 等於是讓 Claude Code 多了一組更精確的工具，它會自己判斷什麼時候該用。

參考資源

延伸閱讀

回到列表

作品案例

看看我們打造的產品與專案。從 WordPress 外掛到 AI 客服方案，每一個作品都是實戰經驗的累積。

瀏覽作品案例

服務項目

WordPress 開發、WooCommerce 電商、LINE 整合、AI 解決方案，依據你的需求提供最適合的技術服務。

瀏覽服務項目

Contact

聯絡我們

若你有任何技術需求、專案諮詢或合作想法，歡迎隨時與我們聊聊(首次諮詢免費）。

  • 想打造 WordPress 網站或 WooCommerce 電商
  • 需要 LINE 整合或 AI 功能導入
  • 有產品點子想找技術合夥人一起實現
  • 既有網站需要改版升級或效能優化
  • 尋找長期穩定的技術顧問合作夥伴
聯絡我們