OpenCode LSP 配置：启用语言服务器与故障排查

语言服务器提供未解析名称、类型错误等诊断，帮助 OpenCode 检查修改。接受代码前，仍应运行项目自己的测试和类型检查。

本独立教程重点介绍启用步骤与故障定位，配置行为已于 2026 年 10 月 2 日对照官方 LSP 文档核对。阅读旧版本教程时，请同时确认本机版本。

启用 OpenCode LSP

当前官方文档说明 LSP 默认关闭。在项目的 opencode.json 中添加以下配置，已有配置时合并该字段：

bash

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

修改后，从项目目录重新启动 OpenCode。开启功能只是第一步，对应语言服务器仍需要满足运行条件。

需要单独覆盖某个服务器的设置时，可以使用对象：

bash

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

不要用示例替换整个配置文件，应保留已有的模型、提供商与项目设置。

检查语言服务器的运行条件

先确认正在编辑的文件属于哪种语言：

语言	服务器	首先检查
JavaScript / TypeScript	`typescript`	已安装项目的 TypeScript 依赖
Python	`pyright`	OpenCode 使用的环境可以运行 Pyright
Go	`gopls`	可以运行 Go 工具链
Rust	`rust`	可以运行 `rust-analyzer`

TypeScript 项目应使用原有包管理器与锁文件恢复依赖。使用 pnpm 的仓库，不需要为了排查 LSP 再生成一个 npm 锁文件。Python 项目应先激活目标环境，再启动 OpenCode；其他终端或虚拟环境中能找到的服务器，不一定对当前进程可见。

Go 项目可先检查：

bash

go version

完整服务器列表及各自的要求请参阅官方文档。只有一种语言出问题时，没有必要安装所有服务器。

解决 LSPs are disabled

按照以下顺序定位：

运行 opencode --version 记录版本；版本过旧时参阅安装与升级指南。
检查项目 opencode.json 和全局 ~/.config/opencode/opencode.json，查找 lsp: false 或服务器的 disabled: true。
使用上面的配置明确启用 LSP，然后从正确的项目目录重新启动。
检查文件扩展名与对应服务器的依赖条件。开启 LSP 并不会安装项目的全部依赖。
使用一个文件复现并查看日志，求助时保留错误原文、版本和相关配置。

调试日志可以帮助区分功能关闭与服务器启动失败：

bash

opencode --log-level DEBUG --print-logs

分享日志前检查私有路径和凭据。启动失败与明确关闭是不同问题，不应使用同一个修复步骤。

禁止下载服务器

OPENCODE_DISABLE_LSP_DOWNLOAD=true 会阻止自动下载语言服务器，它与 lsp 配置是两个设置。如果环境启用了这个变量，应检查所需服务器是否已安装且可以访问；仅设置 lsp: true 不会解除下载限制。

只有一种语言出问题

如果 TypeScript 诊断正常、Python 诊断异常，优先检查 Pyright 和 Python 环境。不要同时修改所有 LSP 设置，否则难以判断是哪一步解决了问题。

配置自定义语言服务器

指定本机已安装的命令及其处理的扩展名：

bash

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

这是配置模板，应根据服务器自己的文档替换可执行文件、参数和扩展名。先在同一环境运行服务器的帮助命令，再排查 OpenCode；配置本身无法修复不存在的可执行文件。

关闭单个服务器或全部 LSP

仅关闭 TypeScript：

bash

{
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

关闭整个功能时，在配置中使用 "lsp": false。

继续阅读 Plan 与 Build 模式、配置和故障排查，区分安装问题、配置问题与具体开发任务。