> ## 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 常见问题

> 排查 Windsurf Editor 的常见问题，包括速率限制、macOS 安全警告、Windows 更新、Linux 崩溃以及终端相关问题。

<div id="general-faq">
  ### 常见问题
</div>

<AccordionGroup>
  <Accordion title="我已经订阅了 Pro，为什么仍然是 Free 套餐？">
    请先等待几分钟以完成更新。如果仍无效，请在网站上退出 Windsurf，重启你的 IDE，然后重新登录 Windsurf。此外，请确保已安装 Windsurf 的最新版本。
  </Accordion>

  <Accordion title="如何取消我的 Pro/Teams 订阅？">
    你可以在 [Windsurf 网站](https://windsurf.com/profile)上，点击右上角头像进入个人资料页面，取消付费方案。

    要取消 Pro 订阅，请在左侧导航中进入 `账单` 页面并点击“Cancel Plan”。

    要取消 Teams 订阅，请在左侧导航中进入 `Manage Team` 页面并点击“Cancel Plan”。
  </Accordion>

  <Accordion title="如何禁用代码片段遥测？">
    如我们的[安全页面](https://windsurf.com/security)所述，你可以前往[账户设置](https://windsurf.com/settings)选择退出代码片段遥测。更多信息请参阅我们的[服务条款](https://windsurf.com/terms-of-service-individual)。
  </Accordion>

  <Accordion title="如何删除我的账户？">
    你可以前往[账户设置](https://windsurf.com/settings)，向下滚动并点击“Delete Account”来删除你的账户。

    <Note>如果你隶属于某个组织，请联系你的管理员。</Note>
  </Accordion>

  <Accordion title="如何提交功能请求？">
    你可以通过我们的社区渠道分享功能请求和反馈：
    [Reddit](https://www.reddit.com/r/windsurf/)、[Discord](https://discord.com/invite/3XFf78nAx5) 或 [Twitter/X](https://x.com/windsurf)。

    你也可以通过我们的[支持平台](https://windsurf.com/support/)联系我们。
  </Accordion>
</AccordionGroup>

<div id="im-experiencing-rate-limiting-issues">
  ### 我遇到了请求频率限制问题
</div>

我们受到速率限制的影响，不幸的是，有时会达到我们所使用的高级 AI 模型的容量上限。我们正积极争取提高这些限制，并公平分配现有的容量。

这不会一直成为问题。如果你遇到此错误，请稍等片刻后再试。

<div id="pylance-or-pyright-isnt-working-python-syntax-highlighting-is-broken-or-subpar">
  ### Pylance 或 Pyright 无法正常工作 / Python 语法高亮失效或效果不佳
</div>

我们已开发了一个[专为 Windsurf 的 Pyright 扩展](/zh/windsurf/advanced/#windsurf-extensions)。请搜索“Windsurf Pyright”，或在扩展搜索中粘贴 `@id:codeium.windsurfPyright`。

<div id="how-do-i-download-diagnostic-logs-to-send-to-the-windsurf-support-team">
  ### 如何下载诊断日志并发送给 Windsurf 支持团队？
</div>

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

<Frame style={{ border: 'none', background: 'none' }}>
  <img src="https://mintcdn.com/codeium/bVGscI7v3lPUsThV/assets/windsurf/windsurf-download-diagnostics.png?fit=max&auto=format&n=bVGscI7v3lPUsThV&q=85&s=b92c1e66d7d6b88e45147038adaae291" width="806" height="612" data-path="assets/windsurf/windsurf-download-diagnostics.png" />
</Frame>

<div id="on-macos-i-see-a-pop-up-windsurf-is-damaged-and-cannot-be-opened">
  ### 在 macOS 上，我看到一个弹窗：“Windsurf 已损坏，无法打开”。
</div>

该弹窗通常是 macOS 安全功能的误报。你可以前往“系统设置 -> 隐私与安全性”，对 Windsurf 点击“允许”或“仍要打开”来解决。如果这不起作用或不可行，请尝试以下步骤：

1. 确保将 Windsurf 放在你的 `/Applications` 文件夹中，并从该位置运行。
2. 检查你的处理器类型：如果你的 Mac 使用 Intel 芯片，请确保下载的是 Intel 版本；如果是 Apple Silicon（如 M1、M2 或 M3），请确保下载 Apple Silicon 版本。你可以在 [Mac 下载页面](https://windsurf.com/windsurf/download_mac) 选择处理器类型。
3. 尝试重新下载 DMG，并从[官方下载页面](https://windsurf.com/windsurf/download_mac)重新安装，因为触发该安全功能的问题通常发生在下载时。
4. 确保 Windsurf（以及“Windsurf 已损坏”的弹窗）已关闭，然后运行 `xattr -c "/Applications/Windsurf.app/"`。

<div id="i-received-an-error-message-about-updates-on-windows-or-updates-are-not-appearing-on-windows">
  ### 我在 Windows 上收到与更新相关的错误消息，或在 Windows 上看不到更新。
</div>

例如：

> 已禁用更新，因为你以管理员身份运行了 Windsurf 的“用户范围”安装。

当以管理员身份运行时，Windsurf 无法自动更新。请在“用户范围”下运行 Windsurf 以进行更新。

<div id="on-macos-remote-ssh-fails-with-undefined-error-0-but-ssh-works-from-terminal">
  ### 在 macOS 上，Remote SSH 报错 “Undefined error: 0”，但在终端中 SSH 正常
</div>

如果 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 会在下次启动时重新触发该提示。

<div id="what-domains-should-i-whitelist-for-network-filtersfirewalls-vpns-or-proxies">
  ### 我需要为网络过滤器/防火墙、VPN 或代理放行哪些域名？
</div>

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

* \*.codeium.com
* \*.windsurf.com
* \*.codeiumdata.com

<div id="on-linux-windsurf-quietly-doesnt-launch-or-crashes-on-launch">
  ### 在 Linux 上，Windsurf 悄无声息地无法启动，或在启动时崩溃
</div>

这通常是由 Electron 的权限问题引起的，VSCode 也会遇到类似情况；在 Linux 上使用 tar 包时，这是预期行为。

最简单的修复方式是运行以下命令：

```bash theme={null}
            sudo chown root:root /path/to/windsurf/chrome-sandbox
            sudo chmod 4755 /path/to/windsurf/chrome-sandbox
```

然后你应该可以启动 Windsurf。你也可以直接运行 `windsurf` 并加上 `--no-sandbox` 参数，不过我们不建议这么做。

如果仍然不行，请尝试以下步骤。

<div id="i-received-an-error-message-saying-windsurf-failed-to-start">
  ### 我收到一条错误消息，显示“Windsurf failed to start”
</div>

<Warning>警告：删除这些文件夹会清除你的对话历史和本地设置！</Warning>

删除以下文件夹：

Windows: `C:\Users\<YOUR_USERNAME>\.codeium\windsurf\cascade`

Linux/Mac: `~/.codeium/windsurf/cascade`

然后尝试重新启动 IDE。

<div id="my-cascade-panel-goes-blank">
  ### 我的 Cascade 面板变成空白
</div>

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

<div id="terminal-session-appears-stuck-in-cascade">
  ### 终端会话在 Cascade 中似乎卡住了
</div>

如果终端命令已经在终端中运行完成，但 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 上下文序列。

<div id="docker-container-not-visible-in-remote-explorer-when-using-wsl">
  ### 在使用 WSL 时 Remote Explorer 中看不到 Docker 容器
</div>

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

```json theme={null}
"terminal.integrated.defaultProfile.osx": "zsh"
```

适用于 Windows：

```json theme={null}
"terminal.integrated.defaultProfile.windows": "PowerShell"
```

适用于 Linux：

```json theme={null}
"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" 来查看所有正在运行的容器列表。