OpenCode LSP 服务器配置

OpenCode 与语言服务器协议（LSP，Language Server Protocol）深度集成，通过 LSP 服务器为 LLM 提供代码诊断、错误提示等实时反馈，帮助 AI 更准确地理解和操作你的代码库。

简单来说，LSP 服务器就是让 OpenCode 具备"读懂代码"能力的组件，类似于 VS Code 中提供代码补全、错误提示的插件。当文件中出现语法错误或类型不匹配时，LSP 服务器会将这些诊断信息反馈给 LLM，从而做出更准确的修改。

工作原理

OpenCode 的 LSP 集成是全自动的，无需手动干预。当 OpenCode 打开一个文件时，会依次执行以下流程：

打开文件
  │
  ▼
读取文件扩展名（如 .ts、.py、.go）
  │
  ▼
与所有已启用的 LSP 服务器进行匹配
  │
  ├── 匹配成功且服务器已运行 → 直接使用
  │
  └── 匹配成功但服务器未运行 → 自动启动对应 LSP 服务器

整个过程在后台静默完成，LSP 服务器启动后会持续为当前会话提供诊断信息。

内置 LSP 服务器

OpenCode 内置了主流语言的 LSP 服务器支持，当检测到对应文件扩展名且满足相应要求时，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（版本 21 及以上）
julials .jl 需要安装 julia 及 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 .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 命令可用
如果你不希望 OpenCode 自动下载 LSP 服务器，可以将环境变量 OPENCODE_DISABLE_LSP_DOWNLOAD 设置为 true 来禁用自动下载行为，详见文末说明。

配置 LSP 服务器

LSP 相关配置写在 opencode.json 的 lsp 字段中。大多数情况下无需任何配置，LSP 会自动启用；但在需要定制行为时，每个 LSP 服务器支持以下配置项：

属性 类型 说明
disabled boolean 设置为 true 可禁用该 LSP 服务器
command string[] 启动 LSP 服务器的命令（数组形式，第一个元素为可执行文件名，其余为参数）
extensions string[] 该 LSP 服务器负责处理的文件扩展名列表
env object 启动服务器时注入的环境变量，键为变量名，值为变量值
initialization object 在 LSP initialize 握手阶段发送给服务器的初始化选项，内容因服务器而异

1、设置环境变量（env）

使用 env 属性在启动 LSP 服务器时注入环境变量。常用于开启调试日志或指定运行时所需的路径：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "rust": {
      "env": {
        "RUST_LOG": "debug"    // 为 rust-analyzer 开启 debug 级别日志，方便排查 LSP 问题
      }
    }
  }
}

2、设置初始化选项（initialization）

initialization 用于向 LSP 服务器传递服务器特定的配置，这些选项在 LSP 握手（initialize 请求）阶段一次性发送，影响该服务器此后的所有行为：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "initialization": {
        "preferences": {
          "importModuleSpecifierPreference": "relative"
          // 告诉 TypeScript LSP 优先使用相对路径导入（如 ./utils）
          // 而不是绝对路径（如 /src/utils）或 tsconfig.json 中配置的路径别名
        }
      }
    }
  }
}
初始化选项因 LSP 服务器而异。例如 typescript 的选项与 gopls 完全不同，使用前请查阅对应 LSP 服务器的官方文档，避免传入无效配置。

禁用 LSP 服务器

1、禁用所有 LSP 服务器

如果完全不需要 LSP 功能，可以将 lsp 整体设置为 false，一次性关闭所有 LSP 服务器：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": false    // 全局禁用所有 LSP 服务器，适合不需要代码诊断或网络/资源受限的环境
}

2、禁用特定 LSP 服务器

如果只想关闭某一个 LSP 服务器而保留其他的，对该服务器单独设置 disabled: true：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "disabled": true    // 只禁用 TypeScript LSP，其他语言的 LSP 服务器不受影响
    }
  }
}

添加自定义 LSP 服务器

如果你使用的语言不在内置支持列表中，可以通过指定 command 和 extensions 来手动添加任意 LSP 服务器，只要该服务器遵循标准的 LSP 协议并支持 --stdio 模式（通过标准输入输出通信）即可：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {                                  // 自定义键名，可随意命名，用于在配置中标识该服务器
      "command": ["custom-lsp-server", "--stdio"],   // 启动命令：第一个元素是可执行文件名，
                                                     // 其余元素是传给它的启动参数
                                                     // --stdio 表示通过标准输入输出与 OpenCode 通信
      "extensions": [".custom"]                      // 指定该 LSP 服务器处理哪些文件扩展名
    }
  }
}

还可以同时为自定义 LSP 服务器配置环境变量和初始化选项，与内置服务器写法完全一致：

实例

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "my-lang-server": {
      "command": ["my-lang-server", "--stdio", "--log-level", "warn"],
      "extensions": [".mylang", ".ml2"],          // 支持同时绑定多个文件扩展名
      "env": {
        "MY_LSP_HOME": "/usr/local/my-lang"       // 为服务器进程注入所需的环境变量
      },
      "initialization": {
        "formatOnSave": true                       // 传递该服务器文档中定义的初始化选项
      }
    }
  }
}

补充说明

PHP Intelephense 许可证

PHP Intelephense 提供免费版和付费高级版。高级版通过许可证密钥解锁，包含导入整理、代码折叠、调用层级查看等增强功能。如果你购买了许可证，将密钥单独写入以下路径的文本文件中即可自动激活，无需任何额外配置：

操作系统 许可证文件路径
macOS / Linux $HOME/intelephense/license.txt
Windows %USERPROFILE%/intelephense/license.txt

许可证文件中只需包含许可证密钥本身，不要添加任何其他内容（包括多余的空格或换行符），否则可能导致激活失败。

禁用自动下载

OpenCode 默认会在检测到对应文件扩展名时自动从网络下载所需的 LSP 服务器。如果你处于网络受限的环境，或希望完全手动管理 LSP 工具，可以通过设置以下环境变量来禁用自动下载：

# Linux / macOS：临时禁用（仅当前终端会话有效）
export OPENCODE_DISABLE_LSP_DOWNLOAD=true

# Linux / macOS：永久禁用（写入 shell 配置文件）
echo 'export OPENCODE_DISABLE_LSP_DOWNLOAD=true' >> ~/.bashrc
source ~/.bashrc

# Windows（PowerShell：仅当前会话）
$env:OPENCODE_DISABLE_LSP_DOWNLOAD = "true"

禁用后，OpenCode 不会再自动下载任何 LSP 服务器，但已预先安装在系统中的 LSP 工具仍然可以正常被检测和使用。