安裝、登入與首次啟動

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

本章目標：在一臺新機器上安裝 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 重新啟動，所以第一次重點是選對遷移路徑，不必一次性完成所有偏好。

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 個關鍵選擇：

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

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

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

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

這條路徑適合處理：

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

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

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

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

windsurf .

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

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

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

5. 更新入口和版本判斷

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

看到按鈕：選單欄右上角出現 Restart to Update -> 時直接點選。這是常態——Windsurf 已檢測到新版並下載好了。
看不到按鈕：右上角 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 或受控市場源。

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

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

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

8. 第一天不要做什麼

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

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

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

深讀：為什麼安裝教程要覆蓋遠端開發

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

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

本章自檢

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

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

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

官方來源

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