---
title: "安裝、登入與首次啟動"
description: "按 Windsurf 官方文件跑通系統要求、下載、onboarding、VS Code/Cursor 匯入、PATH、認證、更新、遠端開發和第一輪安全驗證。"
verifiedAt: "2026-05-09"
---

Windsurf 的安裝教程不能只寫“下載安裝”。官方首次啟動頁把 Cascade、Usage、Terminal、MCP、Memories、Context Awareness、Advanced、Workflows、App Deploys 都放在歡迎頁入口裡，說明 Windsurf 的第一步是把 IDE、賬號、專案目錄和低風險 agent 閉環一起跑通。

> [!TIP]
> **本章目標**：在一臺新機器上安裝 Windsurf，完成登入和配置匯入，確認 `windsurf .` 可用，並用只讀 Cascade 任務驗證它能正確理解當前專案。

## 1. 先確認平臺要求

官方安裝頁在 2026-05-06 給出的最低要求是：

| 平臺 | 官方最低要求 | 實操判斷 |
| --- | --- | --- |
| macOS | OS X Yosemite | 普通現代 macOS 通常滿足；企業裝置重點檢查應用許可權、登入回跳和代理證書 |
| Windows | Windows 10 | 如果專案實際在 WSL 內，還要單獨驗證 WSL 連線和檔案系統效能 |
| Ubuntu | `>= 20.04`，或 `glibc >= 2.31`、`glibcxx >= 3.4.26` | 老映象要先查系統庫版本 |
| Other Linux | `glibc >= 2.28`、`glibcxx >= 3.4.25` | 發行版越舊，越要先驗證依賴和桌面執行環境 |

如果 Windsurf 無法開啟、白屏、擴充套件異常或認證失敗，不要先懷疑 Cascade。先排除系統版本、企業代理、SSL inspection、證書、登入回撥和桌面許可權。

## 2. Onboarding 按順序做

首次開啟 Windsurf 後會進入 onboarding。官方說明這個流程後續可以用 `Reset Onboarding` 重新啟動，所以第一次重點是選對遷移路徑，不必一次性完成所有偏好。

```mermaid
flowchart TD
    Download["下載並安裝 Windsurf"] --> Setup["選擇 setup flow"]
    Setup --> Fresh["Start fresh"]
    Setup --> Import["Import from VS Code / Cursor"]
    Fresh --> Keys["選擇 keybindings"]
    Import --> Theme["匯入 settings / extensions"]
    Keys --> Theme
    Theme --> Auth["Sign up / Log in"]
    Auth --> Open["Open Windsurf"]
    Open --> Path["確認 windsurf PATH"]
    Path --> First["開啟專案做只讀驗證"]

    style Auth fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style First fill:#dcfce7,stroke:#16a34a,stroke-width:2px
```

onboarding 裡有 4 個關鍵選擇：

1. **Setup flow**：從零開始，或從 VS Code / Cursor 匯入。
2. **Keybindings**：Start fresh 時可選預設 VS Code 快捷鍵或 Vim。
3. **Theme**：可先選預設；如果匯入 VS Code，匯入主題可能覆蓋此處選擇。
4. **Account**：Windsurf 需要賬號才能使用；註冊免費，但企業網路可能影響瀏覽器回跳。

從 VS Code 或 Cursor 遷移時，優先匯入 settings 和 extensions，這樣能保留熟悉的快捷鍵、主題、格式化器和語言工具。不要把匯入理解成“完全複製原編輯器”：依賴 VS Code 專有 API、AI 補全衝突、遠端開發擴充套件和企業市場源的外掛，仍要逐項驗證。

## 3. 登入失敗先走官方手動認證

官方提供了 “Having Trouble?” 的手動認證路徑：複製認證連結到瀏覽器，登入後把 authentication code 填回 Windsurf。

這條路徑適合處理：

- 預設瀏覽器和當前登入環境不一致。
- 瀏覽器隱私設定或企業策略攔截 deep link。
- 代理、SSL inspection 或零信任閘道器改寫認證跳轉。
- 遠端桌面、虛擬機器或受控裝置阻止應用接收回撥。

> [!IMPORTANT]
> **不要把登入失敗直接歸因於賬號壞了**。先確認認證連結能開啟、瀏覽器能完成登入、Windsurf 能接收回撥；不行再走手動 code。

## 4. 安裝 PATH 後從專案目錄開啟

onboarding 可以把 `windsurf` 安裝到 PATH。完成後建議從真實專案目錄啟動：

```bash
windsurf .
```

這個習慣能減少兩個常見錯誤：在錯誤目錄啟動 Cascade，或讓 Cascade 以為當前 workspace 是空專案。開啟專案後，第一輪只做低風險驗證：

| 驗證項 | 推薦提示詞 | 透過標準 |
| --- | --- | --- |
| 專案識別 | “只讀解釋這個專案的技術堆疊和主要目錄，不要修改檔案。” | 能說出框架、入口、構建/測試線索 |
| 當前檔案 | 選中一個檔案後讓它解釋職責 | 能引用當前檔案內容，不泛泛介紹 |
| 終端輸出 | 選中一段報錯或日誌後傳送 | 能區分錯誤位置、可能根因和下一步驗證 |
| 命令邊界 | “列出建議命令，不要執行。” | 只列命令和理由，不直接執行 |

第一天的目標不是讓它改完整專案，而是確認本機、賬號、專案索引、終端上下文和人工審批邊界都正常。

## 5. 更新入口和版本判斷

官方更新入口按"看不看到按鈕"分兩條路：

1. **看到按鈕**：選單欄右上角出現 `Restart to Update ->` 時直接點選。這是常態——Windsurf 已檢測到新版並下載好了。
2. **看不到按鈕**：右上角 profile dropdown 裡選 `Check for Updates`；或者用快捷鍵 `Cmd+Shift+P`（macOS）/ `Ctrl+Shift+P`（Windows / Linux）開啟 Command Palette，輸入 `Check for Updates` 執行。

哪條路用什麼場景：右上角按鈕是日常更新；profile dropdown / Command Palette 是"Windsurf 啟動時沒拉到更新檢查"或"想強制重新查一下"的兜底。

Windsurf 屬於高頻更新的 AI IDE。模型、用量、Cascade 模式、MCP、Workflows、企業策略和排障入口都可能變化。遇到教程和介面不一致時，先看當前版本、官方 changelog 和官方文件更新時間，再判斷是不是本機配置問題。

## 6. 遠端開發能力不要混裝

官方 Advanced Configuration 頁面說明，Windsurf 自帶 Remote-SSH，使用前需要系統安裝 OpenSSH；入口在 Command Palette 的 `Remote-SSH` 或左下角 `Open a Remote Window`。它目前主要支援連線 Linux-based remote hosts。

幾個邊界要記住：

- 不要安裝 Microsoft `Remote - SSH` 或 `open-remote-ssh`，官方提示這些會和 Windsurf 自帶支援衝突。
- 如果 Remote-SSH 出問題，先確認普通終端裡 `ssh` 能連，再看 `Output > Remote SSH (Windsurf)`。
- SSH agent-forwarding 預設開啟；異常時可以 reload window 重新整理連線。
- Dev Containers 支援本地和 SSH 遠端，但需要 Docker 在對應機器上可用，並且專案包含 `devcontainer.json` 或等價配置。
- Windows 上 WSL 是 beta 支援；如果專案在 WSL 內，先驗證連線穩定性，再讓 Cascade 跑任務。

## 7. 擴充套件市場和推薦擴充套件

Windsurf 可以在 Settings 裡修改 Extension Marketplace URL。團隊環境裡這很重要：企業可能要求使用內部映象、Open VSX 或受控市場源。

首次遷移建議按這個順序處理擴充套件：

1. 先匯入語言服務和格式化器，例如 Python、ESLint、Prettier、Git 工具。
2. 再匯入主題和 UI 輔助擴充套件。
3. 最後處理可能和 Windsurf AI 能力衝突的補全、聊天、AI commit 或命令擴充套件。

如果某個擴充套件導致啟動慢、快捷鍵衝突或補全異常，先停用它，再確認 Windsurf Tab、Cascade 和終端是否恢復正常。

## 8. 第一天不要做什麼

不建議第一次就做這些事：

- 讓 Cascade “重構整個專案”。
- 直接允許它安裝依賴、刪除檔案或跑任意終端命令。
- 在生產後臺、支付、CMS、雲平臺裡測試瀏覽器或部署能力。
- 把金鑰目錄、構建產物、大快取、日誌歸檔交給索引。
- 沒看 diff 就接受一組大改動。

更穩的順序是：只讀解釋專案 → 單檔案小修 → 看 diff → 跑本地驗證 → 再擴大到多檔案任務。

<details>
<summary>深讀：為什麼安裝教程要覆蓋遠端開發</summary>

Windsurf 是 IDE，不是單純網頁服務。真實開發經常發生在 SSH 主機、Dev Container、WSL 或公司受控裝置裡。只要 workspace 不在本機普通目錄，安裝是否成功就不再只看 App 能不能開啟，還要看遠端檔案系統、終端、Docker、OpenSSH、代理證書和擴充套件市場是否可用。

因此，第一天的驗收不應該是“能登入”，而是“能在真實專案所在位置完成只讀理解和受控命令建議”。
</details>

## 本章自檢

完成本章後，用這 6 個問題檢查：

1. 當前系統是否滿足官方最低要求？
2. 你是否知道如何重跑 onboarding？
3. VS Code / Cursor 遷移後，哪些擴充套件需要額外驗證？
4. 瀏覽器回跳失敗時，是否知道手動 authentication code 路徑？
5. `windsurf .` 是否能從專案目錄開啟 IDE？
6. 你是否完成過一次“只讀解釋專案，不改檔案、不執行命令”的 Cascade 驗證？

透過標準：你可以在新機器上覆現安裝流程，並能把安裝、登入、PATH、遠端連線、擴充套件和第一次安全驗證分別定位。

## 官方來源

- [Welcome to Windsurf](https://docs.windsurf.com/windsurf/getting-started) —— 官方安裝、onboarding、系統要求、登入、PATH、更新和首次嘗試入口。
- [Advanced Configuration](https://docs.windsurf.com/windsurf/advanced) —— 官方 SSH、Dev Containers、WSL、Extension Marketplace、diff zones 和 gitignore access 配置。
- [Windsurf llms.txt](https://docs.windsurf.com/llms.txt) —— 官方文件索引，用於核對後續 Cascade、Terminal、MCP、Memories、Workflows 等頁面。

## 接下來去哪

<Cards>
  <Card title="Cascade 核心能力" description="繼續理解 Code/Plan/Ask、工具呼叫、Todo、checkpoint、Agent Command Center 和多會話邊界。" href="/zh-Hant/docs/windsurf/official/01-cascade-core" />
  <Card title="上下文與規則" description="把 Context Awareness、Memories、Rules、AGENTS.md 和 .codeiumignore 的職責邊界一次分清。" href="/zh-Hant/docs/windsurf/official/02-context-rules-agents" />
</Cards>
