Настройка LSP-сервера OpenCode

OpenCode глубоко интегрируется с Language Server Protocol (LSP), используя LSP-серверы для предоставления LLM обратной связи в реальном времени, такой как диагностика кода и подсказки об ошибках, помогая ИИ более точно понимать вашу кодовую базу и работать с ней.

Проще говоря, LSP-сервер — это компонент, который даёт OpenCode возможность «читать код», подобно плагинам в VS Code, обеспечивающим автодополнение кода и подсказки об ошибках. Когда в файле появляется синтаксическая ошибка или несоответствие типов, LSP-сервер передаёт эту диагностическую информацию обратно в LLM, позволяя ей вносить более точные изменения.

Как это работает

Интеграция LSP в OpenCode полностью автоматическая и не требует ручного вмешательства. Когда 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 (устанавливается через Xcode на macOS)
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 поддерживает следующие параметры конфигурации:

Свойство Type Описание
disabled boolean Установить вtrueчтобы отключить этот сервер LSP
command string[] Команда для запуска сервера LSP (в виде массива; первый элемент — имя исполняемого файла, остальные — аргументы)
extensions string[] Список расширений файлов, обрабатываемых этим сервером LSP
env object Переменные среды, внедряемые при запуске сервера; ключи — имена переменных, значения — значения переменных
initialization object Во время LSPinitializeфазы рукопожатия, параметры инициализации, отправляемые серверу; содержимое зависит от сервера

1. Настройка переменных среды (env)

Используйтеenvсвойство для внедрения переменных среды при запуске сервера LSP. Обычно используется для включения отладочного логирования или указания путей, необходимых среде выполнения:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "rust": {
      "env": {
"RUST_LOG": "debug" // Включает логирование уровня debug для rust-analyzer, чтобы упростить диагностику проблем с LSP
      }
    }
  }
}

2. Настройка параметров инициализации (initialization)

initializationИспользуются для передачи конфигурации, специфичной для сервера, LSP-серверу. Эти параметры отправляются один раз во время фазы LSP-рукопожатия (initializerequest) и влияют на всё последующее поведение сервера:

Пример

{
  "$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 // Отключает только LSP для TypeScript; 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 по-прежнему могут обнаруживаться и использоваться как обычно.

Другие расширения