---
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="/docs/windsurf/official/01-cascade-core" />
  <Card title="上下文与规则" description="把 Context Awareness、Memories、Rules、AGENTS.md 和 .codeiumignore 的职责边界一次分清。" href="/docs/windsurf/official/02-context-rules-agents" />
</Cards>
