跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt

Use this file to discover all available pages before exploring further.

​
常见问题

请先等待几分钟以完成更新。如果仍无效，请在网站上退出 Windsurf，重启你的 IDE，然后重新登录 Windsurf。此外，请确保已安装 Windsurf 的最新版本。
你可以在 Windsurf 网站上，点击右上角头像进入个人资料页面，取消付费方案。要取消 Pro 订阅，请在左侧导航中进入 账单 页面并点击“Cancel Plan”。要取消 Teams 订阅，请在左侧导航中进入 Manage Team 页面并点击“Cancel Plan”。
如我们的安全页面所述，你可以前往账户设置选择退出代码片段遥测。更多信息请参阅我们的服务条款。
你可以前往账户设置，向下滚动并点击“Delete Account”来删除你的账户。
如果你隶属于某个组织，请联系你的管理员。
你可以通过我们的社区渠道分享功能请求和反馈： Reddit、Discord 或 Twitter/X。你也可以通过我们的支持平台联系我们。

​
我遇到了请求频率限制问题

我们受到速率限制的影响，不幸的是，有时会达到我们所使用的高级 AI 模型的容量上限。我们正积极争取提高这些限制，并公平分配现有的容量。 这不会一直成为问题。如果你遇到此错误，请稍等片刻后再试。

​
Pylance 或 Pyright 无法正常工作 / Python 语法高亮失效或效果不佳

我们已开发了一个专为 Windsurf 的 Pyright 扩展。请搜索“Windsurf Pyright”，或在扩展搜索中粘贴 @id:codeium.windsurfPyright。

​
如何下载诊断日志并发送给 Windsurf 支持团队？

你可以打开 Cascade 面板，点击右上角的更多菜单（三个点），然后选择“Download Diagnostics”。

​
在 macOS 上，我看到一个弹窗：“Windsurf 已损坏，无法打开”。

该弹窗通常是 macOS 安全功能的误报。你可以前往“系统设置 -> 隐私与安全性”，对 Windsurf 点击“允许”或“仍要打开”来解决。如果这不起作用或不可行，请尝试以下步骤：
  1. 确保将 Windsurf 放在你的 /Applications 文件夹中，并从该位置运行。
  2. 检查你的处理器类型：如果你的 Mac 使用 Intel 芯片，请确保下载的是 Intel 版本；如果是 Apple Silicon（如 M1、M2 或 M3），请确保下载 Apple Silicon 版本。你可以在 Mac 下载页面 选择处理器类型。
  3. 尝试重新下载 DMG，并从官方下载页面重新安装，因为触发该安全功能的问题通常发生在下载时。
  4. 确保 Windsurf（以及“Windsurf 已损坏”的弹窗）已关闭，然后运行 xattr -c "/Applications/Windsurf.app/"。

​
我在 Windows 上收到与更新相关的错误消息，或在 Windows 上看不到更新。

例如：
已禁用更新，因为你以管理员身份运行了 Windsurf 的“用户范围”安装。
当以管理员身份运行时，Windsurf 无法自动更新。请在“用户范围”下运行 Windsurf 以进行更新。

​
在 macOS 上，Remote SSH 报错 “Undefined error: 0”，但在终端中 SSH 正常

如果 Windsurf 中的 Remote SSH 立即失败，而同一个 SSH 连接在终端、VS Code 或其他应用中可以正常工作，通常是因为 macOS 阻止了 Windsurf 的本地网络访问。 在 Remote - SSH 的输出日志中（View → Output → Remote - SSH），你会看到： 
debug1: Connecting to <hostname> port 22.
ssh: connect to host <hostname> port 22: Undefined error: 0
随后会看到 SSH server closed unexpectedly. Error code: 255。 Undefined error: 0 这条消息（而不是 “Connection refused” 或 “Network unreachable”）是关键信号——这是在“隐私与安全性”中未授予应用本地网络权限时，macOS 返回的错误。 要解决此问题：
  1. 打开 系统设置 → 隐私与安全性 → 本地网络。
  2. 在列表中找到 Windsurf，并开启对应开关。
  3. 重启 Windsurf，然后重试连接。
如果 Windsurf 没有出现在“本地网络”列表中，先尝试在 Windsurf 中发起一次 SSH 连接，以触发 macOS 的权限请求提示。如果之前已关闭该提示且仍看不到开关，删除并重新安装 Windsurf 会在下次启动时重新触发该提示。

​
我需要为网络过滤器/防火墙、VPN 或代理放行哪些域名？

如果你使用网络过滤、防火墙、VPN 服务，或在受限网络环境中工作，可能会遇到与 Windsurf 的连接问题。为确保正常运行，请在网络配置中将以下域名加入白名单：
  • *.codeium.com
  • *.windsurf.com
  • *.codeiumdata.com

​
在 Linux 上，Windsurf 悄无声息地无法启动，或在启动时崩溃

这通常是由 Electron 的权限问题引起的，VSCode 也会遇到类似情况；在 Linux 上使用 tar 包时，这是预期行为。 最简单的修复方式是运行以下命令： 
            sudo chown root:root /path/to/windsurf/chrome-sandbox
            sudo chmod 4755 /path/to/windsurf/chrome-sandbox
然后你应该可以启动 Windsurf。你也可以直接运行 windsurf 并加上 --no-sandbox 参数，不过我们不建议这么做。 如果仍然不行，请尝试以下步骤。

​
我收到一条错误消息，显示“Windsurf failed to start”

警告：删除这些文件夹会清除你的对话历史和本地设置！
删除以下文件夹： Windows: C:\Users\<YOUR_USERNAME>\.codeium\windsurf\cascade Linux/Mac: ~/.codeium/windsurf/cascade 然后尝试重新启动 IDE。

​
我的 Cascade 面板变成空白

如果发生这种情况，请联系​​我们！非常感谢您提供屏幕录制。通常清除您的 Chat 历史记录（~/.codeium/windsurf/cascade）即可解决。

​
终端会话在 Cascade 中似乎卡住了

如果终端命令已经在终端中运行完成，但 Cascade 仍然显示该会话正在进行或已卡住，可能是由多种问题导致的： 未设置默认终端配置文件 这可能是因为没有显式设置默认终端配置文件。要解决此问题，你可以在编辑器设置中配置默认终端配置文件。 打开设置界面（Cmd/Ctrl + ,），搜索 “terminal default profile”，然后为你的操作系统设置合适的值。或者，你也可以在 settings.json 中添加以下内容： 适用于 macOS： “terminal.integrated.defaultProfile.osx”: “zsh” 适用于 Windows： “terminal.integrated.defaultProfile.windows”: “PowerShell” 适用于 Linux： “terminal.integrated.defaultProfile.linux”: “bash” 将该值替换为你首选的 shell（例如 bash、zsh、PowerShell、Command Prompt 等）。 自定义 zsh 主题 在某些情况下，高度自定义的 zsh 主题（例如来自 Oh My Zsh、Powerlevel10k 或其他提示符框架的主题）也可能导致 Cascade 在命令已经执行完成后仍认为其正在运行。要检查是否由此导致： 在文本编辑器中打开你的 ~/.zshrc 文件。 通过注释掉设置或加载该主题的行来临时禁用主题，例如 ZSH_THEME="..."、source ~/.p10k.zsh 或 eval "$(oh-my-posh init zsh)"。 保存文件，重启 Windsurf（或在 Windsurf 中打开一个新的终端），然后再次运行一个命令。 如果终端会话在 Cascade 中不再显示为卡住状态，你可以选择在 ~/.zshrc 中保留一个更简单的主题，或者为 Windsurf 终端单独创建一个最小化的 zsh 配置，以便你的其他终端仍然可以使用更复杂的主题。 Systemd 终端上下文跟踪（Linux） 在某些较新的 Linux 发行版（有报告称在 Fedora 43 及之后版本）中，shell 启动链（~/.bashrc → /etc/bashrc → /etc/profile.d/80-systemd-osc-context.sh）可能会启用 systemd “terminal context tracking,” 功能，它会通过 PS0 或 PROMPT_COMMAND 发出 OSC 3008 转义序列。这些额外的控制序列可能会干扰 Cascade 的输出解析，导致命令看起来像是卡住了，或者导致捕获的输出看起来丢失或被截断——即使终端实际上已经正确显示了这些内容。 要规避此问题，可以通过在 ~/.bashrc 中不再 source /etc/bashrc，或者为 Windsurf/Cascade 单独创建一个最小化的 shell 配置文件，来防止在 Cascade 终端中发出 OSC 上下文序列。

​
在使用 WSL 时 Remote Explorer 中看不到 Docker 容器

当连接到 WSL 中的 Docker 容器时，Remote Explorer 窗口可能不会显示可供连接的容器，迫使用户只能使用命令面板作为变通方案。使用 Cmd+P（macOS）或 Ctrl+P（Windows）打开命令面板，然后选择 → “Dev Containers: Attach to Running Container” 来查看所有正在运行的容器列表。 
"terminal.integrated.defaultProfile.osx": "zsh"
适用于 Windows： 
"terminal.integrated.defaultProfile.windows": "PowerShell"
适用于 Linux： 
"terminal.integrated.defaultProfile.linux": "bash"
将该值替换为你首选的 shell（例如 bash、zsh、PowerShell、Command Prompt 等）。 自定义 zsh 主题 在某些情况下，高度自定义的 zsh 主题（例如来自 Oh My Zsh、Powerlevel10k 或其他提示符框架的主题）也可能导致 Cascade 在命令已经执行完成后仍认为其正在运行。要检查是否由此导致：
  1. 在文本编辑器中打开你的 ~/.zshrc 文件。
  2. 通过注释掉设置或加载该主题的行来临时禁用主题，例如 ZSH_THEME="..."、source ~/.p10k.zsh 或 eval "$(oh-my-posh init zsh)"。
  3. 保存文件，重启 Windsurf（或在 Windsurf 中打开一个新的终端），然后再次运行一个命令。
如果终端会话在 Cascade 中不再显示为卡住状态，你可以选择在 ~/.zshrc 中保留一个更简单的主题，或者为 Windsurf 终端单独创建一个最小化的 zsh 配置，以便你的其他终端仍然可以使用更复杂的主题。 Systemd 终端上下文跟踪（Linux） 在某些较新的 Linux 发行版（有报告称在 Fedora 43 及之后版本）中，shell 启动链（~/.bashrc → /etc/bashrc → /etc/profile.d/80-systemd-osc-context.sh）可能会启用 systemd “terminal context tracking,” 功能，它会通过 PS0 或 PROMPT_COMMAND 发出 OSC 3008 转义序列。这些额外的控制序列可能会干扰 Cascade 的输出解析，导致命令看起来像是卡住了，或者导致捕获的输出看起来丢失或被截断——即使终端实际上已经正确显示了这些内容。 要规避此问题，可以通过在 ~/.bashrc 中不再 source /etc/bashrc，或者为 Windsurf/Cascade 单独创建一个最小化的 shell 配置文件，来防止在 Cascade 终端中发出 OSC 上下文序列。

​
Docker Container Not Visible in Remote Explorer When Using WSL

当连接到 WSL 中的 Docker 容器时，Remote Explorer 窗口可能不会显示可供连接的容器，迫使用户只能使用命令面板作为变通方案。使用 Cmd+P（macOS）或 Ctrl+P（Windows）→ “Dev Containers: Attach to Running Container” 来查看所有正在运行的容器列表。