File size: 9,958 Bytes
89a2873 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 | ---
title: LSP 服务器
description: OpenCode 与你的 LSP 服务器集成。
---
OpenCode 可以与语言服务器协议（LSP）服务器集成，将诊断信息作为 agent 的反馈。
---
## 内置支持
OpenCode 内置了多种适用于主流语言的 LSP 服务器：
| LSP 服务器 | 扩展名 | 要求 |
| ------------------ | ------------------------------------------------------------------- | ----------------------------------------------------- |
| astro | .astro | 为 Astro 项目自动安装 |
| bash | .sh, .bash, .zsh, .ksh | 自动安装 bash-language-server |
| clangd | .c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++ | 为 C/C++ 项目自动安装 |
| csharp | .cs | 需要已安装 `.NET SDK` |
| clojure-lsp | .clj, .cljs, .cljc, .edn | 需要 `clojure-lsp` 命令可用 |
| dart | .dart | 需要 `dart` 命令可用 |
| deno | .ts, .tsx, .js, .jsx, .mjs | 需要 `deno` 命令可用（自动检测 deno.json/deno.jsonc） |
| elixir-ls | .ex, .exs | 需要 `elixir` 命令可用 |
| eslint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue | 项目中需要 `eslint` 依赖 |
| fsharp | .fs, .fsi, .fsx, .fsscript | 需要已安装 `.NET SDK` |
| gleam | .gleam | 需要 `gleam` 命令可用 |
| gopls | .go | 需要 `go` 命令可用 |
| hls | .hs, .lhs | 需要 `haskell-language-server-wrapper` 命令可用 |
| jdtls | .java | 需要已安装 `Java SDK (version 21+)` |
| julials | .jl | 需要安装 `julia` and `LanguageServer.jl` |
| kotlin-ls | .kt, .kts | 为 Kotlin 项目自动安装 |
| lua-ls | .lua | 为 Lua 项目自动安装 |
| nixd | .nix | 需要 `nixd` 命令可用 |
| ocaml-lsp | .ml, .mli | 需要 `ocamllsp` 命令可用 |
| oxlint | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte | 项目中需要 `oxlint` 依赖 |
| php intelephense | .php | 为 PHP 项目自动安装 |
| prisma | .prisma | 需要 `prisma` 命令可用 |
| pyright | .py, .pyi | 需要已安装 `pyright` 依赖 |
| ruby-lsp (rubocop) | .rb, .rake, .gemspec, .ru | 需要 `ruby` 和 `gem` 命令可用 |
| rust | .rs | 需要 `rust-analyzer` 命令可用 |
| sourcekit-lsp | .swift, .objc, .objcpp | 需要已安装 `swift`（macOS 上为 `xcode`） |
| svelte | .svelte | 为 Svelte 项目自动安装 |
| terraform | .tf, .tfvars | 从 GitHub releases 自动安装 |
| tinymist | .typ, .typc | 从 GitHub releases 自动安装 |
| typescript | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts | 项目中需要 `typescript` 依赖 |
| vue | .vue | 为 Vue 项目自动安装 |
| yaml-ls | .yaml, .yml | 自动安装 Red Hat yaml-language-server |
| zls | .zig, .zon | 需要 `zig` 命令可用 |
LSP 默认关闭。启用后，当检测到上述文件扩展名且满足相应要求时，服务器会启动。
:::note
你可以将 `OPENCODE_DISABLE_LSP_DOWNLOAD` 环境变量设置为 `true` 来禁用 LSP 服务器的自动下载。
:::
---
## 工作原理
启用 LSP 且 opencode 打开文件时，它会：
1. 将文件扩展名与所有已启用的 LSP 服务器进行匹配。
2. 如果对应的 LSP 服务器尚未运行，则自动启动它。
---
## 最佳实践
LSP 可以通过语言服务器诊断帮助 agent 发现并修复问题。这对某些项目很有用，但并不总是带来净收益。
语言服务器可能与项目不同步、占用较多内存、随版本或项目表现不同，并拖慢 agent 工作流。在许多项目中，更好的做法是让 agent 直接运行 lint、typecheck 或其他诊断类 CLI 工具，这样错误会进入 agent 循环，同时避免这些权衡。将这些命令记录在 `AGENTS.md` 或 skills 等指令文件中，让 agent 知道该运行什么。当你的项目能从额外的语言服务器反馈中受益时再启用 LSP。
---
## 配置
你可以通过 opencode 配置文件中的 `lsp` 部分来启用并自定义 LSP 服务器。
要启用所有内置 LSP 服务器，请将 `lsp` 设置为 `true`。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"lsp": true
}
```
使用对象可以在保持内置服务器启用的同时配置覆盖项或自定义服务器。
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"lsp": {}
}
```
每个 LSP 服务器支持以下配置项：
| 属性 | 类型 | 描述 |
| ---------------- | -------- | --------------------------------- |
| `disabled` | boolean | 设置为 `true` 可禁用该 LSP 服务器 |
| `command` | string[] | 启动 LSP 服务器的命令 |
| `extensions` | string[] | 该 LSP 服务器需要处理的文件扩展名 |
| `env` | object | 启动服务器时设置的环境变量 |
| `initialization` | object | 发送给 LSP 服务器的初始化选项 |
下面来看一些示例。
---
### 环境变量
使用 `env` 属性在启动 LSP 服务器时设置环境变量：
```json title="opencode.json" {5-7}
{
"$schema": "https://opencode.ai/config.json",
"lsp": {
"rust": {
"env": {
"RUST_LOG": "debug"
}
}
}
}
```
---
### 初始化选项
使用 `initialization` 属性向 LSP 服务器传递初始化选项。这些是在 LSP `initialize` 请求期间发送的服务器特定设置：
```json title="opencode.json" {5-9}
{
"$schema": "https://opencode.ai/config.json",
"lsp": {
"typescript": {
"initialization": {
"preferences": {
"importModuleSpecifierPreference": "relative"
}
}
}
}
}
```
:::note
初始化选项因 LSP 服务器而异。请查阅你所使用的 LSP 服务器的文档以了解可用选项。
:::
---
### 禁用 LSP 服务器
如果省略 `lsp`，所有 LSP 服务器都会被禁用。如果另一个配置启用了 LSP，可将 `lsp` 设置为 `false` 来禁用所有 LSP 服务器：
```json title="opencode.json" {3}
{
"$schema": "https://opencode.ai/config.json",
"lsp": false
}
```
要禁用**特定的** LSP 服务器，将 `disabled` 设置为 `true`：
```json title="opencode.json" {5}
{
"$schema": "https://opencode.ai/config.json",
"lsp": {
"typescript": {
"disabled": true
}
}
}
```
---
### 自定义 LSP 服务器
你可以通过指定命令和文件扩展名来添加自定义 LSP 服务器：
```json title="opencode.json" {4-7}
{
"$schema": "https://opencode.ai/config.json",
"lsp": {
"custom-lsp": {
"command": ["custom-lsp-server", "--stdio"],
"extensions": [".custom"]
}
}
}
```
---
## 补充信息
### PHP Intelephense
PHP Intelephense 通过许可证密钥提供高级功能。你可以将许可证密钥单独放在以下路径的文本文件中：
- macOS/Linux：`$HOME/intelephense/license.txt`
- Windows：`%USERPROFILE%/intelephense/license.txt`
该文件应仅包含许可证密钥，不要添加其他任何内容。
|