AI 程式設計教程中文版
官方教程中文版入門

連線 IDE

在 VS Code、Cursor、Windsurf、VSCodium 等 IDE 中使用 OpenCode。

OpenCode 可以與 VS Code、Cursor 或任何支援終端的 IDE 配合使用。它的核心仍然是終端裡的 opencode，IDE 擴充套件主要負責開啟、聚焦和傳遞上下文。

這一篇用 5 分鐘換什麼：你會知道 IDE 整合解決什麼問題、常用快捷鍵是什麼、怎麼自動安裝擴充套件，以及擴充套件沒有安裝時先排查哪裡。

先給結論：IDE 負責上下文，TUI 負責執行

IDE 整合不要理解成另一套 OpenCode。更準確的關係是：

flowchart LR
  IDE["VS Code / Cursor / Windsurf"] --> Context["當前檔案 / 選中內容 / 檔案引用"]
  Context --> Terminal["整合終端"]
  Terminal --> TUI["OpenCode TUI"]
  TUI --> Project["專案檔案 / Git / 測試命令"]

  style IDE fill:#dbeafe,stroke:#3b82f6
  style TUI fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Project fill:#fef3c7,stroke:#f59e0b

你仍然應該按 TUI 的安全方式工作：先只讀、限定檔案、看工具詳情、檢查 diff。

官方 IDE 頁給出的定位很短：OpenCode integrates with VS Code, Cursor, or any IDE that supports a terminal。關鍵不是擴充套件本身，而是“在 IDE 終端裡啟動 OpenCode，並把當前選擇、標籤頁、檔案引用交給終端會話”。因此新手要把 IDE 整合當成上下文入口，不要把它當成許可權邊界。

IDE 整合解決什麼

場景IDE 幫你做什麼仍然要由 OpenCode TUI 做什麼
讀當前檔案自動共享 selection 或 tab判斷上下文是否足夠、是否需要更多檔案
引用檔案行插入 @File#L37-42基於引用生成修改計劃或解釋
快速開會話在分屏終端開啟或聚焦 OpenCode執行工具、顯示 diff、請求確認
多次切任務新建新的 terminal session保持會話邊界，不把不相關上下文混在一起
編輯器回寫/editor 或 /export 呼叫外部編輯器等編輯器關閉後繼續處理訊息

這也是為什麼官方安裝方式是“開啟 IDE 整合終端，執行 opencode”，而不是讓你單獨配置一個複雜的 IDE 後臺服務。

常用操作

  • 快速啟動：Cmd+Esc（Mac）或 Ctrl+Esc（Windows/Linux）在分屏終端檢視中開啟 OpenCode；如果已有終端會話，會自動聚焦。
  • 新建會話：Cmd+Shift+Esc（Mac）或 Ctrl+Shift+Esc（Windows/Linux）啟動新的 OpenCode 終端會話。
  • 上下文感知：自動將當前選中內容或標籤頁共享給 OpenCode。
  • 檔案引用：Cmd+Option+K（Mac）或 Alt+Ctrl+K（Linux/Windows）插入檔案引用，例如 @File#L37-42。

自動共享上下文很方便，但不要把包含金鑰、客戶資料、內部日誌或未公開策略的檔案選中後直接發給模型。

使用邊界

IDE 能讓上下文輸入更快，也更容易誤發內容。建議預設遵守這幾條：

  1. 選中內容只包含當前任務需要的片段，不把整份 .env、日誌、客戶資料、私有策略放進 selection。
  2. 檔案引用優先引用小範圍行號，例如 @File#L37-42，不要把大目錄當作第一輪輸入。
  3. 開新功能、修 bug、做 review 分別用不同 session，避免歷史上下文串線。
  4. 修改前要求 OpenCode 說明將讀取和修改哪些檔案。
  5. 修改後回到 IDE Source Control 或 Git diff 做人工複查。

如果你已經在終端裡熟悉 OpenCode，IDE 整合只是減少複製貼上，不改變驗收標準。

安裝方式

在 VS Code 及其常見分支上，最簡單的方式是在整合終端裡執行：

opencode

擴充套件會自動安裝。支援的 IDE 包括 VS Code、Cursor、Windsurf、VSCodium 等。

如果你希望在 TUI 中執行 /editor 或 /export 時使用自己的 IDE，需要設定 EDITOR：

export EDITOR="code --wait"

GUI 編輯器通常需要 --wait，否則編輯器一開啟，OpenCode 可能就認為訊息已經結束。

手動安裝

如果自動安裝失敗，可以在擴充套件商店中搜尋 OpenCode，然後點選 Install。

驗收步驟

安裝完成後，用一個安全的小任務驗收，不要直接讓它改生產程式碼：

1. 在 IDE 集成终端运行 opencode
2. 用快捷键打开或聚焦 OpenCode 分屏
3. 选中当前文件中一小段无敏感内容
4. 用文件引用快捷键插入 @File#Lx-y
5. 让 OpenCode 只解释这段代码，不编辑
6. 再让它生成修改计划，不执行
7. 最后关闭会话，确认没有误改文件

這輪透過後，再嘗試單檔案文案、小範圍重新命名或只讀 review。

故障排除

如果擴充套件未能自動安裝，先檢查：

  • 是否是在 IDE 的整合終端中執行 opencode。
  • IDE 對應的 CLI 命令是否已安裝。
  • VS Code：code。
  • Cursor：cursor。
  • Windsurf：windsurf。
  • VSCodium：codium。
  • IDE 是否有許可權安裝擴充套件。

如果 CLI 命令缺失，按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows/Linux），搜尋 Shell Command: Install 'code' command in PATH，或安裝對應 IDE 的 shell command。

還有一個常見誤判：你在系統終端執行了 opencode，但期待 IDE 自動安裝擴充套件。官方寫的是在 IDE integrated terminal 中執行。普通終端不會知道當前 IDE 的 extension host，也就不能完成同樣的自動安裝路徑。

接下來去哪

TUI 工作流

IDE 只是承載終端，核心操作仍然是 `@`、`!`、`/` 和 diff 檢查。

快捷鍵

如果 IDE、終端和 OpenCode 快捷鍵衝突，從 keybinds 頁開始調整。

入門

回到第一天安全閉環，確認安裝、provider、只讀和單檔案寫入都跑通。

分享會話

從 IDE 裡分享上下文前，先理解公開連結和資料邊界。

官方資料

使用 TUI

說明 OpenCode 終端介面的基本操作、常見狀態和新手第一次使用的檢查點。

分享會話

說明 OpenCode 會話分享的用途、公開邊界、撤銷方式和團隊預設策略。

本頁目錄

先給結論：IDE 負責上下文，TUI 負責執行IDE 整合解決什麼常用操作使用邊界安裝方式手動安裝驗收步驟故障排除接下來去哪官方資料