安装、登录与首次启动

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 等页面。