LowHow 文档

中文

English

中文

English

深色模式

OpenCode LSP 集成实战教程：为 Go、TypeScript、Python 配置 AI 代码诊断 ​

📚 分类: 开发工具配置 ⏱️ 预计耗时: 30 分钟 🎯 难度: 中级 🔧 环境要求: 已安装 OpenCode 终端 AI 助手 🌐 原文来源: OpenCode 官方文档 - LSP 集成

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 LSP（语言服务器协议）在 OpenCode 中的作用
  • [ ] 为 Go、TypeScript、Python 等主流语言配置 LSP 服务器
  • [ ] 使用 OpenCode 的 AI 助手自动检测和修复代码错误
  • [ ] 解决 LSP 集成过程中的常见问题

最终效果 ​

想象一下：你在终端里用 AI 助手写代码，当你写完一行有语法错误的代码时，AI 能立刻告诉你：“嘿，第 42 行有个类型错误，变量 name 未定义。” 本教程将带你实现这种“智能代码审查”的体验。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
OpenCode最新版opencode --version
Node.js≥ 18.0 (用于 TypeScript/JavaScript)node -v
Go≥ 1.18 (用于 Go)go version

1. 了解 LSP 是什么 ​

🤔 为什么要这样做？ LSP（Language Server Protocol，语言服务器协议）是一个标准协议，它就像一个“翻译官”，让代码编辑器（或像 OpenCode 这样的 AI 工具）能理解不同编程语言的语法、错误和警告。配置了 LSP，你的 AI 助手就能像专业的 IDE（如 VS Code）一样，实时告诉你代码哪里出了问题。

第 1 步：创建 OpenCode 配置文件 ​

🎯 目标：在你的项目根目录下创建一个 .opencode.json 文件，这是 OpenCode 读取配置的核心文件。

📝 操作：

  1. 导航到项目根目录：打开终端，使用 cd 命令进入你的项目文件夹。
  2. 创建配置文件：在项目根目录下，创建一个名为 .opencode.json 的文件。
  3. 写入基础配置：将以下内容复制到文件中。这是一个基础模板，我们稍后会为具体语言进行配置。
json
// .opencode.json
{
  "lsp": {
    "go": { 
      "command": "gopls"
    }, 
    "typescript": { 
      "command": "typescript-language-server", 
      "args": ["--stdio"] 
    }, 
    "python": { 
      "command": "pyright-langserver", 
      "args": ["--stdio"] 
    } 
  }
}

💡 提示：

  • command 字段是语言服务器可执行文件的名称或路径。你需要确保这个命令在你的系统 PATH 环境变量中。
  • args 是传递给语言服务器的命令行参数。--stdio 告诉服务器通过标准输入/输出来通信，这是 OpenCode 要求的。

✅ 验证： 执行以下命令，确保你配置的服务器命令是可用的：

bash
$ which gopls
# 预期输出：/home/user/go/bin/gopls (或类似路径)

$ which typescript-language-server
# 预期输出：/usr/local/bin/typescript-language-server (或类似路径)

如果命令未找到，请先安装对应的语言服务器（见下一步）。

第 2 步：安装并配置具体语言服务器 ​

🎯 目标：为你的项目语言安装对应的 LSP 服务器，并完成特定配置。

2.1 配置 Go (gopls) ​

📝 操作：

  1. 安装 gopls：
    bash
    $ go install golang.org/x/tools/gopls@latest
  2. 确认 .opencode.json 配置：确保配置文件中的 go 部分如下所示。
    json
    // .opencode.json
{
  "lsp": {
    "go": {
      "disabled": false,   // 确保未禁用
      "command": "gopls"   // gopls 不需要额外参数
    }
  }
}

✅ 验证： 在 Go 项目中创建一个包含错误的文件（例如 main.go），然后启动 OpenCode。AI 助手应该能识别出 Go 相关的语法错误。

2.2 配置 TypeScript (typescript-language-server) ​

📝 操作：

  1. 安装服务器和编译器：
    bash
    $ npm install -g typescript-language-server typescript
  2. 确认 .opencode.json 配置：确保配置文件中的 typescript 部分如下所示。
    json
    // .opencode.json
{
  "lsp": {
    "typescript": {
      "disabled": false,
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  }
}
  3. 确保项目配置文件存在：OpenCode 会自动打开 tsconfig.json 和 package.json 来帮助 TypeScript 服务器正确初始化。请确保你的项目根目录下有这两个文件。

✅ 验证： 在 TypeScript 文件中故意写一个类型错误，例如 const a: number = 'hello';，AI 助手应该能检测到并报告类型不匹配。

2.3 配置 Python (pyright) ​

📝 操作：

  1. 安装 pyright：
    bash
    $ npm install -g pyright
    ⚠️ 注意：虽然 Pyright 是用 Python 写的工具，但它通常通过 npm 安装，因为它本身是一个 Node.js 应用程序。
  2. 确认 .opencode.json 配置：确保配置文件中的 python 部分如下所示。
    json
    // .opencode.json
{
  "lsp": {
    "python": {
      "disabled": false,
      "command": "pyright-langserver",
      "args": ["--stdio"]
    }
  }
}

✅ 验证： 在 Python 文件中，写一个未定义的变量，例如 print(x)，AI 助手应该会报告“未定义变量”的错误。

第 3 步：使用 AI 助手进行错误诊断 ​

🎯 目标：学习如何让 AI 助手主动检查代码错误。

📝 操作：

  1. 自动诊断：当你使用 AI: view <文件名>、AI: edit <文件名> 或 AI: write <文件名> 命令后，OpenCode 会自动显示该文件或项目的诊断信息。

  2. 手动诊断：你也可以直接请求 AI 助手检查错误。在 OpenCode 的对话中，输入：

    检查 src/main.ts 的错误

    AI 助手会调用诊断工具，并返回类似下面的结果：

    <file_diagnostics>
Error: /path/to/src/main.ts:42:10 [typescript][2304] Cannot find name 'foo'
Warn: /path/to/src/main.ts:56:5 [typescript][6133] 'unused' is declared but never used
</file_diagnostics>

🤔 这代表什么意思？

  • Error: 严重错误，代码无法编译或运行。
  • Warn: 潜在问题，代码可能能运行，但不推荐这么做。
  • Hint: 改进建议，例如代码可以简化。

✅ 验证： 如果你看到类似上面的诊断信息输出，说明 LSP 集成配置成功，AI 助手已经能理解你的代码错误了。

第 4 步：实战：用 AI 修复代码错误 ​

🎯 目标：体验一个完整的“发现错误 -> 修复错误 -> 验证修复”的工作流。

📝 操作：

假设你的 src/api.ts 文件中有类型错误。

  1. 发现问题：对 AI 说：

    查看 src/api.ts 的错误

    AI 会返回诊断信息。

  2. 让 AI 修复：对 AI 说：

    修复 src/api.ts 中的所有类型错误

    AI 会分析错误并尝试修改代码。它可能会使用 edit 或 write 工具。

  3. 验证修复：AI 修改文件后，会自动再次检查诊断。如果仍有错误，它可能会告诉你“错误已减少，但仍有 x 个问题”。此时，你可以继续迭代修复：

    如果还有错误，继续修复

✅ 验证： 当 AI 最终回复“所有错误已修复”时，你可以通过再次查看诊断来确认：

查看 src/api.ts 的错误

应该会看到 <diagnostic_summary>Current file: 0 errors, 0 warnings</diagnostic_summary>。

进阶技巧（可选） ​

开启调试模式 ​

如果你遇到问题，可以开启调试模式来查看更详细的日志。

  1. 修改配置：
    json
    // .opencode.json
{
  "debugLSP": true,
  "debug": true
}
  2. 运行 OpenCode：
    bash
    $ opencode -d
    调试日志会输出到终端，并保存在 ~/.opencode/logs/ 目录下。你可以按 Ctrl+L 在 OpenCode 界面内查看日志。

常见问题 (FAQ) ​

Q1: 配置后，AI 助手没有报告任何错误。A: 请按以下顺序排查：

  1. 服务器是否启动？ 检查配置文件中的 command 路径是否正确。在终端运行 which <command> 确认。
  2. 文件类型是否匹配？ 确保 language-id (如 go, typescript) 与你的文件扩展名 (.go, .ts) 对应。
  3. 项目是否配置正确？ TypeScript 项目需要 tsconfig.json，Go 项目需要 go.mod。OpenCode 需要这些文件来理解项目结构。
  4. 服务器是否繁忙？ 大型项目可能需要一些时间完成索引。等待 5-10 秒后重试。

Q2: 报错 command not found: typescript-language-serverA: 说明你还没有安装它，或者安装路径不在 PATH 中。执行 npm install -g typescript-language-server 后重试。如果使用 nvm 等 Node 版本管理工具，请确保全局模块的路径已添加到 PATH。

Q3: 同一个文件，AI 助手和 VS Code 显示的错误不一致。A: 这可能是因为 OpenCode 和 VS Code 使用了不同的 LSP 服务器或配置。请确保你的 .opencode.json 配置与 VS Code 的设置（通常在 settings.json 中）一致。另外，确保你的 LSP 服务器版本是最新的。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. LSP 是什么：它是一个标准协议，让 AI 助手能理解代码的语法和错误。
  2. 如何配置：通过修改 .opencode.json 文件，告诉 OpenCode 使用哪个语言服务器。
  3. 如何诊断：AI 助手可以自动或按需显示代码中的错误、警告和改进建议。
  4. 工作流：你可以让 AI 助手“发现问题 -> 修复问题 -> 验证修复”，形成一个高效的代码纠错闭环。

© 2026 LowHow