連線 LSP 伺服器

LSP 讓 OpenCode 拿到更接近 IDE 的程式碼訊號：診斷、副檔名匹配、語言伺服器反饋和部分語言生態的初始化資訊。它適合提高程式碼理解質量，但不應該替代測試、型別檢查和人工 review。

先給結論：LSP 是診斷訊號，不是構建結果

OpenCode 開啟檔案時，如果 LSP 已啟用，會按副檔名匹配對應語言伺服器；滿足依賴要求時，啟動合適的 LSP server，把診斷資訊反饋給 LLM。

flowchart LR
    File["開啟檔案"] --> Match["按副檔名匹配 LSP"]
    Match --> Requirement["檢查依賴 / 命令 / 專案依賴"]
    Requirement --> Server["啟動 language server"]
    Server --> Diagnostics["返回診斷訊號"]
    Diagnostics --> Agent["幫助 agent 判斷程式碼問題"]
    Agent --> Verify["仍需測試 / 型別檢查驗證"]

    style Diagnostics fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style Verify fill:#fee2e2,stroke:#ef4444

適合依賴 LSP 的任務：

• 找定義、引用和跨檔案關係。
• 利用型別錯誤或診斷定位問題。
• 修復區域性語法、型別、匯入和介面不一致。
• 讓 agent 在大型程式碼庫裡少靠全文猜測。

不適合只靠 LSP 判斷的任務：

• 構建是否透過。
• 測試是否覆蓋。
• 執行時行為是否正確。
• 外部 API、資料庫、許可權、部署狀態。

1. 啟用 LSP

官方當前配置裡，如果省略 lsp，所有 LSP server 都是停用狀態。要啟用所有內建 LSP server，顯式寫：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": true
}

如果你想保留内置 server，同时配置覆盖项或自定义 server，可以写成对象：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {}
}

2. 内置 LSP 怎么判断

OpenCode 内置支持多种语言服务器，但它们的前提不同。不要把“支持”理解成“所有机器都会自动可用”。

如果你不希望 OpenCode 自动下载 LSP server，可以设置：

export OPENCODE_DISABLE_LSP_DOWNLOAD=true

这适合受管控的企业机器、离线环境、CI 或必须走内部镜像的开发环境。

3. 配置项怎么写

每个 LSP server entry 支持这些字段：

官方文档提醒：server entry 通常需要 command，除非它只是用来禁用一个 server。

4. 给 server 注入环境变量

例如给 Rust LSP 开调试日志：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "rust": {
      "command": ["rust-analyzer"],
      "env": {
        "RUST_LOG": "debug"
      }
    }
  }
}

环境变量只应该放运行时需要的非敏感配置。许可证、token、内部服务凭据不要随手写进项目配置。

5. 传初始化选项

initialization 会在 LSP initialize 请求期间发送给 server。不同语言服务器支持的字段不一样，要看对应 LSP 文档。

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"],
      "initialization": {
        "preferences": {
          "importModuleSpecifierPreference": "relative"
        }
      }
    }
  }
}

6. 禁用 LSP

要在当前配置里禁用所有 LSP server：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": false
}

只禁用某个 server：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

适合禁用的场景包括：server 启动慢、诊断噪音过大、monorepo 解析错误、企业环境禁止自动下载、某个语言服务器版本和项目冲突。

7. 添加自定义 LSP server

自定义 server 至少要给 command 和 extensions：

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"]
    }
  }
}

先在终端里确认命令本身可用，再交给 OpenCode：

which custom-lsp-server
custom-lsp-server --help

如果 server 依賴專案根目錄、虛擬環境、SDK 路徑或內部證書，把這些前提寫進專案說明，不要讓 agent 每次重新猜。

8. PHP Intelephense 許可證

PHP Intelephense 的高階功能需要許可證。官方說明可以把許可證金鑰單獨放在文本檔案裡：

• macOS / Linux：$HOME/intelephense/license.txt
• Windows：%USERPROFILE%/intelephense/license.txt

檔案裡只放許可證 key，不要放註釋、賬號、說明或其他內容。

9. 驗收清單

啟用 LSP 後，用這幾項驗收：

• 目標語言的依賴或本機命令可用。
• opencode.json 明確寫了 lsp。
• 自動下載符合當前機器和企業策略。
• 自定義 server 的 command 能在終端獨立執行。
• LSP 診斷和專案 typecheck / lint / test 沒有明顯矛盾。
• 發現噪音或錯誤時，能快速停用單個 server。

接下來去哪

官方資料

• OpenCode LSP Servers：https://opencode.ai/docs/lsp
• OpenCode Tools：https://opencode.ai/docs/tools
• OpenCode Configuration：https://opencode.ai/docs/config
• OpenCode Formatters：https://opencode.ai/docs/formatters