Windsurf AI编辑器零基础教程：2026完全指南

TL;DR

Windsurf 是 Codeium 推出的 AI 原生代码编辑器——基于 VS Code 深度定制，从底层为 AI 辅助开发重新设计。如果你想让 AI 直接在你的编辑器里读代码、写代码，而不是在聊天机器人和编辑器之间来回复制粘贴，Windsurf 提供了 Cascade（能理解整个项目并直接修改代码的 AI 代理）和 Supercomplete（上下文感知的智能行内补全）。本教程带你从安装到精通，覆盖真正省时间的实操流程。

你将学到

• 5 分钟内在 macOS、Windows 或 Linux 上安装 Windsurf
• 配置 AI 模型 — Claude Sonnet 4.5、GPT-5 以及免费替代方案
• 使用 Supercomplete 获得智能行内代码建议
• 掌握 Cascade 进行多文件 AI 代理编程
• 配置 .windsurfrules 实现项目级 AI 行为定制
• 排查常见问题并优化工作流

前置条件

• 一台运行 macOS 12+、Windows 10/11 或 Linux（Ubuntu 20.04+）的电脑
• 至少 4 GB 空闲内存（推荐 8 GB）
• 联网以访问 AI 模型
• 可选：已有的 VS Code 配置/插件（Windsurf 可一键导入）

第一步：安装 Windsurf

macOS

# 方式 A：从 windsurf.com 下载

# 访问 https://windsurf.com，下载 .dmg 安装包

# 将 Windsurf 拖入 Applications 文件夹

# 方式 B：Homebrew（如可用）
brew install --cask windsurf

Windows

从 windsurf.com 下载 .exe 安装程序并运行。安装程序会自动处理一切——无需手动配置 PATH。

Linux

# Debian/Ubuntu
wget https://windsurf.com/windsurf.deb
sudo dpkg -i windsurf.deb

# 或使用 AppImage
wget https://windsurf.com/windsurf.AppImage
chmod +x windsurf.AppImage
./windsurf.AppImage

首次启动 — 导入 VS Code 配置

首次启动时，Windsurf 会询问是否从 VS Code 导入配置、插件、快捷键和主题。选择"从 VS Code 导入"——这会给你一个熟悉的起点，所有快捷键都保留。导入是单向且非破坏性的（你的 VS Code 配置不会被修改）。

第二步：配置 AI 模型

打开 Windsurf，进入设置（macOS 上 Cmd+, / Windows/Linux 上 Ctrl+,），搜索"AI"或"Model"。

推荐模型配置（2026 年 6 月）

如何切换模型： 点击 Cascade 侧边栏底部左侧的模型名称下拉菜单。

启用 Supercomplete

Supercomplete 是 Windsurf 的行内代码补全引擎。它基于你的项目上下文建议整行甚至整段代码——比标准自动补全更智能。

1. 打开设置 → 搜索 "supercomplete"
2. 将 Enable Supercomplete 切换为 ON
3. 将 Supercomplete Suggestion Delay 设为 200ms（默认值对大多数用户足够）
4. 在 Supercomplete: Max Tokens 下设为 256（控制建议的最大长度）

Supercomplete 自动运行——只需要开始输入，停顿片刻就会触发建议。按 Tab 接受，按 Esc 取消。

第三步：使用 Cascade — AI 代理引擎

Cascade 是 Windsurf 的核心 AI 代理。不同于在聊天机器人中复制粘贴代码，Cascade 读取你的整个代码库，理解项目结构，并直接在你的文件中进行修改。

打开 Cascade

按 Cmd+L（macOS）或 Ctrl+L（Windows/Linux）打开 Cascade 侧边栏。

Cascade Chat 与 Cascade Agent 的区别

Windsurf 的 Cascade 有两种模式：

• Chat 模式（默认）：提问、获取解释。生成的代码以建议形式呈现，你可以逐条审查。
• Agent 模式（Ctrl+Shift+L）：自主编辑。Cascade 读取文件、修改代码、创建新文件、运行终端命令——全部通过一次提示词完成。每次修改以 diff 形式展示，你可以接受或拒绝。

示例：用 Cascade Agent 构建 REST API 端点

1. 按 Ctrl+Shift+L 打开 Cascade Agent
2. 粘贴以下提示词：

为这个 Node.js Express 应用添加一个 GET /api/users 端点。
包含分页（page 和 limit 查询参数）、
无效参数的错误处理，
并返回 JSON 格式 { users: [], total, page, limit }。

1. Cascade 将：

   • 找到你的 Express 路由文件
   • 读取现有路由模式
   • 编写新的端点代码
   • 展示 diff 差异
   • 等待你接受或拒绝

2. 点击 Accept All（Cmd+Enter）或逐条审查每项修改

Cascade 上下文 — 如何理解你的代码

Cascade 在打开项目时自动索引整个代码库。它能够看到：

• 工作区内的所有文件（排除 .gitignore 中指定的模式）
• 打开的文件标签作为优先上下文
• 最近修改的 Git 历史
• 运行中的终端输出

专业提示： 使用 @filename 显式地将文件添加到 Cascade 的上下文中，以防它遗漏相关内容。

第四步：编写 .windsurfrules 定制项目级 AI 行为

.windsurfrules 是放在项目根目录的 markdown 文件，告诉 Cascade 如何行为。它相当于你的代码库的系统提示词。

创建 .windsurfrules

在项目根目录创建名为 .windsurfrules 的文件：

# Cascade 项目规则

## 技术栈
- Next.js 15 + App Router
- TypeScript 严格模式
- Tailwind CSS v4 样式
- Prisma ORM + PostgreSQL

## 编码规范
- 使用箭头函数，不用 function 声明
- 新页面务必添加错误边界
- 使用 Zod 做 API 校验
- 文件命名：组件用 kebab-case，工具函数用 camelCase

## 测试
- 使用 Vitest 编写测试
- 每个 API 路由至少需要一个集成测试

## 禁止事项
- 禁止使用 `any` 类型 — 先用 `unknown`
- 未经询问不添加新的 npm 依赖
- 未经明确指令不修改 tsconfig.json

保存文件。Cascade 会在每次会话时自动读取。无需重新加载——下次调用 Cascade 时会自动获取更新。

高级 .windsurfrules：使用 @-引用

你可以引用其他文件：

@docs/architecture.md
@docs/api-conventions.md

生成代码时始终遵循上述文档中的模式。

第五步：真正省时间的实操流程

流程 1：跨代码库重构函数

1. 选中任意文件中的函数名
2. 按 Cmd+Shift+L（Agent 模式）
3. 输入：将此函数重命名为 X 并更新项目中所有引用
4. Cascade 找到所有使用位置并全部更新
5. 审查 diff → Accept All

流程 2：为现有模块生成测试

1. 打开要测试的文件
2. 按 Cmd+L → 输入：使用 Vitest 为此模块编写全面的单元测试。覆盖边界情况、错误状态和正常路径。
3. Cascade 读取模块、理解所有导出并编写测试
4. 按 Cmd+Enter 接受

流程 3：结合终端调试

1. 在 Windsurf 内置终端中运行失败的命令
2. 选中终端输出中的错误信息
3. 按 Cmd+L → 输入：修复这个错误（Cascade 获取终端输出作为上下文）
4. Cascade 读取错误、相关文件并提出修复方案

流程 4：使用 Ctrl+K 行内编辑

1. 选中一段代码
2. 按 Ctrl+K（macOS 上 Cmd+K）
3. 输入指令：添加对空字符串和 null 值的输入验证
4. Cascade 原地重写选中的代码块

第六步：优化 Windsurf 设置

性能设置

界面设置（影响很大）

Editor: Minimap                 → OFF（节省侧边栏空间）
Editor: Inlay Hints             → ON（显示推断类型）
Cascade: Show Diff Preview      → ON（接受前先审查）
Cascade: Auto-accept Safe Edits → OFF（始终审查 AI 修改）

关键：保持"Auto-accept Safe Edits"为 OFF。 即使是"安全"的编辑（如格式化）在大型代码库中也可能产生意外副作用。始终审查。

Windsurf vs Cursor vs VS Code Copilot（速览对比）

常见问题排查

Cascade 响应很慢

• 检查网络连接——Cascade 依赖云端模型
• 减少上下文：关闭 Cascade 上下文中不需要的标签页
• 切换到更快的模型（Cascade Base 响应即时但能力较弱）
• 在设置 → Indexing → Exclude 中排除大型目录

Supercomplete 建议不相关

• 确保项目有 .windsurfrules 文件并包含编码规范
• 将相关文件作为标签页打开——Cascade 优先使用已打开文件作为上下文
• 检查文件类型是否被识别（底部状态栏显示语言模式）

Agent 修改了我不打算改的文件

• 始终使用具体、范围明确的提示词启动 Agent 模式
• 提示词开头指定文件路径：在 src/utils/auth.ts 中，添加 JWT 刷新逻辑
• 接受前审查每个 diff——永远不要自动接受 Agent 修改

Windsurf 占用内存过高

• 从索引中排除 node_modules、.next、dist、build
• 关闭不用的项目（Windsurf 会索引所有打开的工作区文件夹）
• 每天重启 Windsurf——长时间会话会累积索引内存

从 VS Code 导入后插件没有过来

Windsurf 使用 VS Code 插件市场，但部分插件可能不兼容。从插件面板（Cmd+Shift+X）手动重新安装。所有标准 VS Code 插件都能正常使用——问题通常只出现在依赖 VS Code 专有内部 API 的插件上。

相关教程

• Claude Code 初学者教程：2026 完整指南
• GitHub Copilot Agent Mode：如何高效使用
• Cursor AI 编辑器教程：安装与最佳实践