安装 Windsurf 桌面版并完成首次配置

Windsurf 是一款把 AI 助手直接嵌进编辑器工作流的桌面 IDE。它解决的核心问题是：让写代码、读代码、跑命令这几件事在同一个窗口里完成，不必在编辑器、终端和浏览器之间来回切换。它适合已经熟悉 VS Code 类编辑器、希望把 AI 会话纳入日常开发流程的开发者，也适合刚接手陌生代码库、需要先让工具帮忙梳理结构的人。本文按安装、引导、配置、首次使用、卸载的顺序，把整套流程讲清楚。如果你只想先了解这个工具的整体定位，可以看站内的 Windsurf 条目，再回来跟着本文操作。

需要提前说明：本文涉及的具体版本号、系统最低要求、套餐与配额等信息会随时间变化，请以官网当前公布的信息为准。文中出现的命令与路径用于说明操作方式，实际执行前建议核对官方安装页面。

准备工作

在下载安装包之前，先把下面几件事确认好，可以避免装到一半卡住。

操作系统版本：macOS 端的最低系统版本为 OS X Yosemite；Windows 端最低为 Windows 10；Linux 端要求 glibc >= 2.28、glibcxx >= 3.4.25，对应 Ubuntu 20、Debian 10、Fedora 36、RHEL 8 这一档及以上的发行版。低于这些版本的机器无法正常运行。
账号：使用 Windsurf 需要登录账号。没有账号的可以在引导流程里免费注册。如果登录环节出问题，还可以改用 API key 手动登录。
安装方式的选择：Linux 用户要特别注意，tar 包形式安装的程序不会自动更新。如果希望后续通过包管理器拿到新版本，应该走 deb 或 rpm 的仓库安装方式，而不是下载 tarball。
已有的编辑器配置：如果你长期使用 VS Code 或 Cursor，建议在安装前想清楚是否要导入原有配置。导入可以在引导流程里做，也可以事后通过命令面板补做。
终端命令的偏好：引导流程里有一个「安装终端命令」的勾选项，勾上之后就能在终端里用命令直接打开项目目录。如果你习惯从命令行启动编辑器，保持勾选。

操作步骤

第一步：下载对应平台的安装包

打开下载页面，按你的操作系统选择安装包。macOS 与 Windows 都是直接下载安装程序；Linux 则分 tar、deb、rpm 三种形式，选择依据是你的发行版包管理体系和是否需要自动更新。

一个容易忽略的细节：Linux 的 tar 包解压即用，但不会自我更新。想持续跟进新版本，就走下面的仓库安装。

第二步：在 deb 系发行版上通过仓库安装

适用于 Ubuntu 20.04 及以上、Debian 10 及以上的系统。先安装下载与密钥工具，导入签名密钥，再写入软件源：

sudo apt-get install wget gpg
wget -qO- "<签名密钥地址>" | gpg --dearmor > windsurf-stable.gpg
sudo install -D -o root -g root -m 644 windsurf-stable.gpg /etc/apt/keyrings/windsurf-stable.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/windsurf-stable.gpg] <仓库地址> stable main" | sudo tee /etc/apt/sources.list.d/windsurf.list > /dev/null
rm -f windsurf-stable.gpg

然后执行安装：

sudo apt install apt-transport-https
sudo apt update
sudo apt install devin-desktop

这里有一个命名上的坑需要留意：仓库地址和文件名里仍然沿用改名前的 windsurf 字样，但实际安装的包名已经是 devin-desktop。windsurf 保留为一个过渡包，会拉取 devin-desktop，所以之前已经装过的机器仍然能正常收到更新。执行安装命令时不要照着旧教程去装 windsurf 包，直接用新包名。

第三步：在 rpm 系发行版上通过仓库安装

适用于 Fedora 36 及以上、CentOS 8 及以上、RHEL 8 及以上的系统。先导入签名密钥并写入仓库配置：

sudo rpm --import <签名密钥地址>
sudo tee /etc/yum.repos.d/windsurf.repo > /dev/null << 'EOF'
[windsurf]
name=Windsurf Repository
baseurl=<仓库地址>
enabled=1
autorefresh=1
gpgcheck=1
metadata_expire=1h
gpgkey=<签名密钥地址>
EOF

然后安装：

sudo dnf check-update
sudo dnf install -y devin-desktop

配置里的 metadata_expire=1h 值得单独说明。它让 dnf 每小时检查一次是否有新版本。早期版本的安装说明漏掉了这一行，dnf 就退回默认的 48 小时缓存周期，结果是新版本发布后最多要等两天才在本地出现，看起来像是更新滞后。如果你是从旧文档抄的配置，记得补上这一行。

第四步：走完引导流程

首次启动会进入引导，一共三步。

选择主题。同时留意「安装终端命令」这个勾选项，保持勾选后就可以在终端里这样启动：devin-desktop ~/Developer/my-project。展开「Import Settings」还能选择你习惯的快捷键方案。
登录或注册。用账号登录即可；没有账号可以免费注册。若登录受阻，可以选择手动登录，向程序提供一个 API key。
开始使用。引导结束后会进入起始页，页面以 AI 输入框为中心。

第五步：导入 VS Code 或 Cursor 配置

如果引导时跳过了导入，事后补做也很简单。打开命令面板，macOS 用 ⌘+⇧+P，Windows 与 Linux 用 Ctrl+Shift+P，然后输入 VS Code 或 Cursor，选择对应的导入命令执行。

需要注意扩展的兼容性：部分扩展无法在 Windsurf 中工作，包括其他 AI 代码补全类扩展和专有扩展。另外，Windsurf 不支持从任何扩展市场安装扩展，这一点和 VS Code 的用法差别较大，迁移前要评估一下你依赖的扩展是否受影响。

第六步：打开项目或连接远程环境

没有打开任何文件夹时，起始页会给出三个入口：打开项目、克隆仓库、通过 SSH 连接。此外也可以连接到本地的 dev container。选择其中一个，把工作目录挂进来。

第七步：发起第一次 AI 会话

在起始页的输入框里输入一个任务并发送，就会开启一个新的 agent 会话。你可以和它对话、让它写代码、让它执行代码。如果还没有任何历史会话，输入框下方会给出建议提示词，例如「探索我的代码库并画出它的工作原理」，点一下就会填入输入框。

用过之后，起始页会显示最近会话。把该标题下的下拉菜单切到「最近项目」，再点「查看全部」可以看到完整列表。点击输入框底部的「前往会话列表」，则可以在 Agent Command Center 里浏览所有会话。

第八步：打开设置

快速设置面板的入口在右下角状态栏，点击设置项即可打开，面板内含套餐信息、设置、AI 快捷键三个标签页。要进入完整设置页，有三种方式：在快速面板里点「高级设置」；在起始页底部点「设置」；或者在右上角头像下拉菜单里选择设置项。

一个完整示例

下面以一台 Ubuntu 22.04 机器为例，从零走到第一次 AI 会话。

1. 确认系统满足要求。检查 glibc 版本：

ldd --version

输出中的版本号需要不低于 2.28。Ubuntu 22.04 默认满足。

2. 添加仓库并安装。按第二步的命令依次执行，先装 wget 与 gpg，导入密钥到 /etc/apt/keyrings/windsurf-stable.gpg，写入 /etc/apt/sources.list.d/windsurf.list，清理临时密钥文件，然后 sudo apt update 并 sudo apt install devin-desktop。

3. 从终端启动并打开项目。假设项目在 ~/Developer/my-project：

devin-desktop ~/Developer/my-project

如果这条命令提示找不到，说明引导时没有勾选安装终端命令，回到设置里补装即可。

4. 登录。在引导界面用账号登录；若失败，改用手动登录并填入 API key。

5. 导入配置。按 Ctrl+Shift+P 打开命令面板，输入 VS Code，执行导入。导入完成后检查一下常用扩展是否还在，尤其是 AI 补全类扩展，它们属于不兼容范围。

6. 发起会话。在起始页输入框里输入「探索我的代码库并画出它的工作原理」，发送。等 agent 返回结果后，可以继续追问具体模块的职责。

7. 验证设置入口。点右下角状态栏的设置项，确认能看到套餐信息、设置、AI 快捷键三个标签页。

注意事项

关于 Linux 的更新机制。tar 包不会自我更新，这是选择安装方式时最容易踩的坑。如果你用 tar 包装了，后续想升级只能手动重新下载。deb 与 rpm 仓库安装则会随包管理器更新。

关于包名与仓库名的错位。仓库地址、repo 文件名、密钥文件名都还带着改名前的 windsurf 字样，但安装的包叫 devin-desktop。照着旧文档装 windsurf 包虽然也能通过过渡包装上，但直接装新包名更清晰。

关于 dnf 的更新延迟。仓库配置里必须包含 metadata_expire=1h，否则 dnf 使用 48 小时默认缓存，新版本最多滞后两天才可见。

关于扩展限制。Windsurf 不支持从任何扩展市场安装扩展，且其他 AI 代码补全类扩展与专有扩展不兼容。迁移前先盘点依赖。

关于自定义图标。这个功能目前处于 beta 阶段，仅对付费用户开放，且只在 macOS 上可用，其他操作系统尚未支持。入口在编辑器右上角的头像/设置图标里，选择「自定义应用图标」。

关于预发布版本。Windsurf 提供一个预发布通道，供希望尽早用上新功能的用户选择加入。新功能通常先在预发布通道推出，随后进入稳定版。预发布版本的功能可能尚未打磨完整，不建议用在关键项目上。

关于卸载与残留。卸载时先确认程序已完全退出，再删除应用本体。macOS 把应用从「应用程序」文件夹拖到废纸篓；Windows 的安装目录通常在 C:\Program Files\Devin 或 C:\Users\[用户名]\AppData\Local\Programs\Devin，改名之前装的版本可能仍在同一位置的 Windsurf 文件夹里，直到重新运行完整安装程序才会变；Linux 则删除你当初安装的目录。

删完应用还不够，配置文件要单独清理。macOS 与 Linux 执行：

rm -rf ~/.codeium/windsurf

Windows 删除这个目录：

C:\Users\[用户名]\.codeium\windsurf

如果当初把程序加进了 PATH，记得从环境变量里移除。用系统包管理器或控制面板安装的，也可以用同样的方式卸载。最后清空废纸篓或回收站。

关于价格与配额。套餐档位、用量额度、付费功能范围都会调整，本文不列具体数字，请以官网当前信息为准。