前置条件
- 1已安装 Windsurf（Windows / macOS / Linux 均有客户端）
- 2已注册 DeepSeek 开放平台并创建 API Key
- 3了解在 IDE 设置里修改配置项
DeepSeek V4.1 接入 Windsurf 完整指南
Windsurf 是 Codeium 团队推出的 AI IDE，特色是 Cascade Agent 模式——AI 能自己读项目、跑命令、连续改多个文件。它支持 BYOK（自带 Key）接第三方模型，配好自己的 DeepSeek Key 后，用量和成本都自己可控。
本篇覆盖完整配置流程和两种模式的用法。
接入方式对比
| 方式 | 模型 | 费用 | 可控性 |
|---|---|---|---|
| Windsurf 自带 | 官方托管模型 | 免费额度 + 订阅 | 版本不可选，额度有限 |
| BYOK 自定义（本篇） | deepseek-chat / deepseek-reasoner | 按量，每百万 token 一两元量级 | 版本、Key、用量明细全自己掌握 |
第一步：创建 DeepSeek API Key
- 登录 DeepSeek 开放平台，完成实名认证
- 进入
API keys页面创建新 Key - 当场复制保存——Key 完整内容只显示这一次
- 新账号赠送额度够跑通本篇全部测试
第二步：添加自定义模型
- 打开 Windsurf 设置（右下角齿轮或
Cmd/Ctrl + ,） - 找到 AI → Providers / 模型提供方 区域，选择添加自定义 Provider，协议选 OpenAI 兼容
- 按下表填写：
| 参数 | 值 |
|---|---|
| 显示名称 | DeepSeek Chat |
| 模型 ID | deepseek-chat |
| API Base | https://api.deepseek.com |
| API Key | sk-你的key |
- 保存后再加一个：模型 ID 填
deepseek-reasoner，显示名 DeepSeek Reasoner，其余相同
如果保存后测试报 404，把 API Base 改成 https://api.deepseek.com/v1 再试——两个地址 DeepSeek 服务端都兼容，不同 Windsurf 版本对路径的拼接行为有差异，两个形式总有一个对。
第三步：验证
- 在 Chat 面板切到 DeepSeek Chat，发一句「你好」，有回复即通
- 打开一个代码文件，让它解释选中代码，确认上下文能带进去
- 切到 DeepSeek Reasoner 问一个多步推理问题，确认能正常收到思维链输出
两种模式的分工
接上模型后，Windsurf 的两种模式建议这样用：
- Chat / Edit 模式：问答、局部改写。日常「这段代码什么意思」「这个函数改一下」直接用
deepseek-chat，快且便宜 - Cascade 模式：跨文件任务。让它「给这个模块加上错误处理」或「按这个接口文档生成客户端代码」，AI 会自动读相关文件并连续修改
复杂任务的标准动作：先用 Reasoner 在 Chat 里出方案，再开 Cascade 执行。Reasoner 的思维链能提前暴露设计问题，比直接让 Agent 闷头改稳得多。
使用建议与成本
- 重要项目先提交 Git 再跑 Cascade——Agent 会直接改多个文件，有版本控制才有回滚余地
- 成本参考：按量计费，输入输出每百万 token 一两元量级，缓存命中更便宜，具体以平台价格页为准
- 用量查询：DeepSeek 开放平台控制台可以看到每次调用的 token 明细，便于复盘哪些任务最烧钱
常见问题排查
| 症状 | 原因 | 解法 |
|---|---|---|
| 404 Not Found | API Base 路径形式不对 | 在带 /v1 和不带之间切换重试 |
| 模型不存在提示 | 模型 ID 拼错 | 只能是 deepseek-chat 或 deepseek-reasoner |
| 401 鉴权失败 | Key 不完整或已删除 | 重新创建 Key，确认 sk- 开头复制完整 |
| 回复变成英文 | 提问太短 | 带上下文，明确「用中文回答」 |
| Cascade 中途停了 | 上下文超限或任务太大 | 把大任务拆成多轮，每轮只让它做一件事 |
| 免费额度用完被限 | 自带模型额度耗尽 | 切到自己的 Key，或在设置里确认当前会话用的提供方 |
同类方案对比
DeepSeek 接入各主流 IDE 的专题都在这里：DeepSeek V4.1 Flash 接入 VS Code 完整指南、DeepSeek V4.1 接入 Cursor 完整指南、DeepSeek V4.1 接入 JetBrains 完整指南、DeepSeek V4.1 接入 Trae 完整指南。选型困难时一句话总结：要插件生态选 VS Code，要开箱即用选 Trae，要 Agent 体验选 Windsurf/Cursor，用 JetBrains 的走 Continue。
常见问题
QWindsurf 自带的免费模型和 DeepSeek 怎么选？
Windsurf 免费额度对轻度用户够用，写 demo、问问题、小改动都覆盖；但额度用完要么订阅要么等刷新，不可控。自己的 DeepSeek Key 按量计费，每百万 token 一两元量级，重度使用月成本通常也是几十元，而且模型版本自己定、用量明细在开放平台逐次可查。建议：轻度体验用自带，每天靠 AI 写代码超过一小时的切 Key。
QAPI Base 到底带不带 /v1？
两个地址 DeepSeek 都接受——官方文档明确 base_url 可以是 https://api.deepseek.com，也兼容 https://api.deepseek.com/v1。所以填 https://api.deepseek.com 如果客户端不自动拼路径就补 /v1。判断方法很简单：保存后发一条测试消息，报 404 就是路径不对，换个形式重试，两个总有一个对。
QCascade 模式用 DeepSeek 效果如何？
Cascade 是 Windsurf 的 Agent 模式，能自己读文件、跑命令、改多文件。接 DeepSeek 后日常任务（加接口、写测试、改配置）完成度不错，但要注意两点：一是复杂任务建议先用 DeepSeek Reasoner 在 Chat 里过方案再让 Cascade 执行，思维链能提前暴露方案问题；二是 Cascade 会创建和修改文件，重要项目先提交 Git 再让它跑，出问题能回滚。同类方案也可以对比 DeepSeek V4.1 Flash 接入 VS Code 完整指南 里的 Cline 路线。