连接 LSP 服务器

LSP 让 OpenCode 拿到更接近 IDE 的代码信号：诊断、文件扩展名匹配、语言服务器反馈和部分语言生态的初始化信息。它适合提高代码理解质量，但不应该替代测试、类型检查和人工 review。

先给结论：LSP 是诊断信号，不是构建结果

OpenCode 打开文件时，如果 LSP 已启用，会按文件扩展名匹配对应语言服务器；满足依赖要求时，启动合适的 LSP server，把诊断信息反馈给 LLM。

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、数据库、权限、部署状态。

1. 启用 LSP

官方当前配置里，如果省略 lsp，所有 LSP server 都是禁用状态。要启用所有内置 LSP server，显式写：

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

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

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

2. 内置 LSP 怎么判断

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

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

export OPENCODE_DISABLE_LSP_DOWNLOAD=true

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

3. 配置项怎么写

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

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

4. 给 server 注入环境变量

例如给 Rust LSP 开调试日志：

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

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

5. 传初始化选项

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

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

6. 禁用 LSP

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

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

只禁用某个 server：

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

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

7. 添加自定义 LSP server

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

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

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

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。

接下来去哪

官方资料

• OpenCode LSP Servers：https://opencode.ai/docs/lsp
• OpenCode Tools：https://opencode.ai/docs/tools
• OpenCode Configuration：https://opencode.ai/docs/config
• OpenCode Formatters：https://opencode.ai/docs/formatters