---

最近把 DeepSeek 接入 Windsurf，填了两遍配置才跑通。第一遍照着 Cursor 的填法，Model Name 写 deepseek-v4-pro，API 返回错误；第二遍把 context_window 设到 128k，长文件补全的后半段莫名丢失，排查了一下午才定位到是 Windsurf 的上下文处理逻辑导致的。这两个坑和 Cursor 的填法不同，记录下来供参考。

说明：DeepSeek 目前对外开放的模型标识符为 deepseek-chat（对应 V3）和 deepseek-reasoner（对应 R1），官方尚未发布名为"V4 Pro"的模型。本文标题和正文已统一使用 deepseek-chat / DeepSeek V3。

这篇适合谁

• 已经在 Cursor 用过 DeepSeek，想迁移到 Windsurf 的
• Windsurf 配置自定义模型后遇到报错或补全不完整的
• 想用 DeepSeek 的编码能力但不想付 Claude 高价的
• 团队里有人用 Windsurf 有人用 Cursor，需要统一配置文档的

整体流程

1. 拿到 DeepSeek API Key
2. 在 Windsurf Settings 里添加 Custom Endpoint
3. 填对 Model Name（这里有坑）
4. 设置 context_window 上限（这里也有坑）
5. 跑一个长文件验证补全完整性

[拿 API Key]
    ↓
[Windsurf Settings > AI Models > Custom（路径因版本而异）]
    ↓
Model Name 怎么填？
  ├─ 填 deepseek-v4-pro → ❌ API 返回模型不存在错误
  └─ 填 deepseek-chat   → ✅ 正常响应
                              ↓
                    context_window 怎么设？
                      ├─ 填 128000 → ❌ 长文件后半段丢失（个人测试结论）
                      └─ 填 64000  → ✅ 补全完整（个人测试结论）

先说结论

配置项	Cursor 填法	Windsurf 填法	填错后果
Model Name	deepseek-chat 可用；deepseek-v4-pro 在 Cursor 中是否有 alias 映射未经官方文档确认	必须填 deepseek-chat	API 返回模型不存在错误
context_window	可以填 128000	建议不超过 64000	长文件补全静默截断（个人测试结论，非官方说明）
Base URL	https://api.deepseek.com/v1	同左	—

第一步：拿 API Key

去 platform.deepseek.com 控制台，创建一个新 Key。格式是 sk-xxxxxxxx，复制时注意不要多带空格。

如果不想直连 DeepSeek 官方（偶尔会遇到限流），也可以走 OpenRouter 等聚合网关，修改 Base URL 即可。后面代码示例会同时给两种写法。

第二步：Windsurf 里添加 Custom Endpoint

注意：以下菜单路径基于写作时的 Windsurf 版本，实际路径可能随版本更新变化，请以当前版本的界面为准。

打开 Windsurf，Cmd+, 进 Settings，找到 AI Models > Custom，点 Add。

三个字段填法如下：

Base URL:   https://api.deepseek.com/v1
API Key:    sk-你的key
Model Name: deepseek-chat

注意 Base URL 末尾不要加 /chat/completions，Windsurf 会自动拼接。如果手动加了完整路径，实际请求会变成 .../v1/chat/completions/chat/completions，导致请求失败。

第三步：Model Name 的坑——必须填 deepseek-chat

这是最容易踩的地方。Windsurf 的 Custom Endpoint 会把你填写的 Model Name 原样传给 API 的 model 字段，不做任何转换。

DeepSeek 官方 API 目前对外开放的模型标识符只有两个：deepseek-chat 和 deepseek-reasoner。如果填了不存在的名称，API 会返回类似下面的错误（具体错误文本以实际返回为准）：

HTTP 400 Bad Request
model 'deepseek-v4-pro' does not exist

关于 Cursor 的填法：有用户反映在 Cursor 中填 deepseek-v4-pro 也能正常调用，但 Cursor 是否在内部做了 alias 映射未见官方文档说明，无法确认。保险起见，两个 IDE 都统一填 deepseek-chat。

第四步：context_window 建议不超过 64000

以下为个人测试结论，Windsurf 内部实现未公开，无法独立核实，仅供参考。

Windsurf 的 Custom Model 配置里有一个上下文长度字段（不同版本可能显示为 context_window 或 maxContextLength，字段名未见官方文档公开说明）。DeepSeek V3 理论上支持 128k 上下文，但在 Windsurf 中填 128000 会出现问题。

现象：打开一个 2000 多行的文件，让它补全某个函数，返回结果只有前半段，后面直接断掉，没有报错提示，静默丢失。

根据个人测试，推测 Windsurf 在声明的上下文长度超过某个内部阈值时，会对上下文进行分片处理，而这个分片方式与 DeepSeek API 的预期输入格式存在不兼容，导致后半段内容丢失。这一推测未经官方确认。

解决办法：将该字段设为 64000 或更低。

context_window: 64000

个人测试数据（仅供参考，结果可能因环境而异）：60000 和 64000 稳定，65536 偶尔出问题，128000 必出问题。

第五步：验证长文件补全

配置完成后，建议先用一个较长的文件测试一下。让它补全一个位于文件末尾的函数，检查返回是否完整。

验证方式示例：在一个 1800 行的 TypeScript 文件最后写 // TODO: implement sortUsers，让 Windsurf 补全。如果能完整返回带 return 语句的函数体，说明上下文没有被截断。

不同场景怎么选

个人开发者，只用 Windsurf：填 deepseek-chat，context_window 设 64000，Base URL 用官方 https://api.deepseek.com/v1。DeepSeek V3 的输入价格为 $0.27/M tokens（缓存未命中，以 DeepSeek 官方定价页为准，价格可能更新），日常编码成本较低。

团队里 Windsurf 和 Cursor 混用：建议统一走一个聚合网关（如 OpenRouter），两个 IDE 共用同一个 Base URL 和 Key，便于统一管理。Windsurf 这边 Model Name 只能填 deepseek-chat，在团队文档里标注清楚。

需要超长上下文的场景（比如整个 monorepo 做 RAG）：Windsurf 目前受上述限制，只能使用 64k 以内的窗口。如果文件经常超过 2000 行，可以考虑使用 Cursor，或直接通过脚本调用 DeepSeek API。

对延迟敏感：以下为个人实测参考值，无官方 SLA 支撑——DeepSeek 官方 API 在亚太区的 P95 延迟大约在 400–600ms，欧美地区可考虑通过聚合网关选择更近的节点。

常见问题 FAQ

Q: Windsurf 配置 DeepSeek 后返回模型不存在错误怎么办？

A: 大概率是 Model Name 填错了。必须填 deepseek-chat，不能填 deepseek-v4-pro 或其他非官方标识符。Windsurf 不做转换，会把填写的值原样发给 API。

Q: 配置后提示 401 Unauthorized 怎么排查？

A: 先去 platform.deepseek.com 确认 Key 是否已激活，再检查复制时是否多带了空格或换行符。具体错误文本以实际返回为准。Windsurf 的输入框有时会截断末尾字符，建议手动核对 Key 的完整性。

Q: 长文件补全只有前半段，后面没了？

A: 将 context_window 改为 64000 或更低，改完重启 Windsurf。详见第四步说明，这是个人测试结论，非官方说明。

Q: Base URL 末尾要不要加 /chat/completions？

A: 不要。填 https://api.deepseek.com/v1 即可，Windsurf 会自动拼接路径。如果手动加了完整路径，实际请求 URL 会重复拼接，导致请求失败。

Q: deepseek-chat 和 deepseek-reasoner 在 Windsurf 里选哪个？

A: 日常写代码用 deepseek-chat（V3），响应快、价格低（输出 $1.10/M tokens，缓存未命中，以官方定价页为准）。deepseek-reasoner（R1）适合需要推理过程的场景，如复杂算法设计，但输出价格更高（$2.19/M tokens，缓存未命中）。另外，R1 的思考过程通过 API 的独立字段 reasoning_content 返回，是否会显示在 Windsurf 的 IDE 界面中取决于 Windsurf 的渲染方式，无法从 API 规范直接确认，建议实测。

小结

两个关键点：Model Name 必须填 deepseek-chat，context_window 建议不超过 64000。前者是因为 Windsurf 不做模型名称转换，后者是个人测试发现的兼容性问题，非官方说明，Windsurf 后续版本可能有所调整。配置正确后，DeepSeek V3 在 Windsurf 中的编码体验较好，响应速度和价格相比部分高端模型有明显优势。