---
title: "連線 IDE"
description: "在 VS Code、Cursor、Windsurf、VSCodium 等 IDE 中使用 OpenCode。"
verifiedAt: "2026-05-09"
---

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

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

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

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

```mermaid
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`。

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

## 使用邊界

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

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

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

## 安裝方式

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

```bash
opencode
```

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

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

```bash
export EDITOR="code --wait"
```

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

## 手動安裝

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

## 驗收步驟

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

```text
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，也就不能完成同樣的自動安裝路徑。

## 接下來去哪

<Cards>
  <Card title="TUI 工作流" description="IDE 只是承載終端，核心操作仍然是 `@`、`!`、`/` 和 diff 檢查。" href="/zh-Hant/docs/opencode/official/00-getting-started/tui" />
  <Card title="快捷鍵" description="如果 IDE、終端和 OpenCode 快捷鍵衝突，從 keybinds 頁開始調整。" href="/zh-Hant/docs/opencode/official/01-customization/keybinds" />
  <Card title="入門" description="回到第一天安全閉環，確認安裝、provider、只讀和單檔案寫入都跑通。" href="/zh-Hant/docs/opencode/official/00-getting-started" />
  <Card title="分享會話" description="從 IDE 裡分享上下文前，先理解公開連結和資料邊界。" href="/zh-Hant/docs/opencode/official/00-getting-started/share" />
</Cards>

## 官方資料

- OpenCode IDE：[https://opencode.ai/docs/ide](https://opencode.ai/docs/ide)
- OpenCode TUI：[https://opencode.ai/docs/tui](https://opencode.ai/docs/tui)
