---
title: "連線 LSP 伺服器"
description: "OpenCode 與你的 LSP 伺服器整合。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **這一篇用 10 分鐘換什麼**：你會知道什麼時候該啟用 LSP、怎麼開啟內建 server、哪些 server 會自動下載，哪些依賴本機命令，以及配置 `env`、`initialization`、停用和自定義 server 時最容易踩哪裡。

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

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

```mermaid
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、資料庫、許可權、部署狀態。

> [!IMPORTANT]
> LSP 是“程式碼理解輔助層”。最後是否正確，仍然要靠專案自己的 `test`、`typecheck`、`lint`、構建和人工 diff review。

## 1. 啟用 LSP

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

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

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

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

> [!WARNING]
> **不要以为 LSP 默认一定打开**：先看项目配置里有没有 `lsp`。如果缺失，按官方说明就是禁用；如果上层配置已经启用，再用项目级配置覆盖。

## 2. 内置 LSP 怎么判断

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

| 类型 | 代表 server | 前提 |
| --- | --- | --- |
| 可自动安装 | `astro`、`bash`、`clangd`、`kotlin-ls`、`lua-ls`、`php intelephense`、`svelte`、`terraform`、`tinymist`、`vue`、`yaml-ls` | 检测到对应项目或扩展名后自动安装 |
| 依赖项目包 | `typescript`、`eslint`、`oxlint`、`pyright` | 项目里要有对应依赖 |
| 依赖本机命令 | `go`/`gopls`、`rust-analyzer`、`dart`、`deno`、`elixir`、`zig`、`nixd`、`ocamllsp`、`clojure-lsp`、`gleam` | 本机命令必须可用 |
| 依赖 SDK 或特殊环境 | `csharp`、`fsharp`、`jdtls`、`razor`、`sourcekit-lsp`、`hls`、`julia` | 需要 .NET、Java 21+、Swift/Xcode、Haskell、Julia 等 |

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

```bash
export OPENCODE_DISABLE_LSP_DOWNLOAD=true
```

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

## 3. 配置项怎么写

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

| 字段 | 作用 |
| --- | --- |
| `disabled` | 设置为 `true` 禁用该 server |
| `command` | 启动 server 的命令数组 |
| `extensions` | 由该 server 处理的文件扩展名 |
| `env` | 启动 server 时注入的环境变量 |
| `initialization` | LSP `initialize` 请求里的初始化选项 |

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

## 4. 给 server 注入环境变量

例如给 Rust LSP 开调试日志：

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

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

## 5. 传初始化选项

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

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

> [!TIP]
> **不要复制别的语言服务器初始化选项**：TypeScript、Rust、Python、Java 的初始化字段不是通用协议。字段写错通常不会让 OpenCode 报很清楚的错，只会让 LSP 行为不像你预期。

## 6. 禁用 LSP

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

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

只禁用某个 server：

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

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

## 7. 添加自定义 LSP server

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

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

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

```bash
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。

## 接下來去哪

<Cards>
  <Card title="工具總覽" description="先理解內建工具、permission、custom tool 和 MCP 的邊界。" href="/zh-Hant/docs/opencode/official/04-tools-mcp/tools" />
  <Card title="格式化器" description="LSP 給診斷，formatter 只做機械格式化，不要混用職責。" href="/zh-Hant/docs/opencode/official/04-tools-mcp/formatters" />
  <Card title="配置" description="檢視 `opencode.json` 裡 server、runtime、provider、permission 和 LSP 的整體關係。" href="/zh-Hant/docs/opencode/official/01-customization/config" />
  <Card title="許可權" description="LSP 之外的工具讀寫能力要靠 permission 控制。" href="/zh-Hant/docs/opencode/official/05-security/permissions" />
</Cards>

## 官方資料

- OpenCode LSP Servers：[https://opencode.ai/docs/lsp](https://opencode.ai/docs/lsp)
- OpenCode Tools：[https://opencode.ai/docs/tools](https://opencode.ai/docs/tools)
- OpenCode Configuration：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
- OpenCode Formatters：[https://opencode.ai/docs/formatters](https://opencode.ai/docs/formatters)
