> ## 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 中的 TLS / SSL 检查问题

> 在企业环境中，当 SSL 检查（例如 Zscaler）导致 TLS 证书验证或协议协商失败时，应如何进行配置。包括如何捕获控制台（Console）错误以及应向 IT/安全团队提出哪些请求。

某些企业或公司网络会对出站 HTTPS 流量执行 TLS 拦截 (“SSL 检查”)  (通常通过 Zscaler 或类似安全网关) 。Windsurf Editor 必须与外部服务建立出站 TLS 连接 (用于登录和依赖云端的功能) 。如果被检查的流量被企业检查 CA 重新签名，而你的机器或运行时并不信任该 CA (或证书链不完整) ，Windsurf 可能会因 SSL/证书或协商错误而无法连接。

在以下情况下，可能需要排查 SSL/TLS 检查问题：

* 你看到 “Failed to connect (连接失败) ” 或类似网络错误

* 编辑器或 Cascade 面板显示空白屏幕且始终无法加载

* Cascade 或其他依赖云端的功能无法加载或连接

* 登录或激活流程意外失败

* 在热点/家庭网络下功能正常，但在公司网络下失败

* 在日志或开发者工具 (devtools) 中看到证书或 TLS 握手错误

<Note>
  如果你同时遇到代理相关问题，请参见 [Proxy Configuration (代理配置) ](/zh/troubleshooting/windsurf-proxy-configuration)。
</Note>

***

<div id="1-check-whether-your-network-uses-ssl-inspection">
  ## 1. 检查你的网络是否使用 SSL 检查
</div>

在更改编辑器中的任何设置之前，先询问你的 IT / 安全 / 网络团队：

* 我们是否对出站 HTTPS 流量执行 TLS 拦截 / SSL 检查？

* 是否对开发者工作站和开发者工具 (不仅仅是浏览器) 启用了 SSL 检查？

* 对被检查的流量签名使用的是哪条 Root CA / Intermediate CA 证书链？

* 该 CA 证书链是否已部署到各终端，并被开发所用的应用程序 / 运行时信任？

如果你的组织不使用 SSL 检查，通常不需要参考本指南。如果你的组织使用 SSL 检查，请继续阅读下面的内容。

***

<div id="2-capture-the-underlying-error-in-windsurf-developer-tools-console">
  ## 2. 在 Windsurf 中捕获底层错误 (Developer Tools → Console)
</div>

基于 VS Code 的 Windsurf Editor 提供了 Developer Tools，可用于查看实际发生的 TLS/证书错误。

1. 打开 **Help → Dev Tools** / **Developer Tools**

2. 选择 **Console** 选项卡

3. 查找 **红色标记的错误**

4. 展开每条错误记录以查看完整详情 (嵌套错误字段 / 堆栈跟踪)

常见错误模式包括：

**证书信任失败 (不受信任的 CA) ：**

* `certificate signed by unknown authority`

* `unable to verify the first certificate`

* `self signed certificate in certificate chain`

* `UNABLE_TO_VERIFY_LEAF_SIGNATURE`

**证书链构建失败 (缺失中间证书) ：**

* `unable to get local issuer certificate`

* `unable to get issuer certificate`

**TLS 协商失败：**

* `handshake_failure`

* `wrong version number`

* `protocol negotiation failed`

* `ERR_SSL_PROTOCOL_ERROR`

如果你能将展开后的控制台错误文本提供给 IT/安全团队，通常可以显著缩短问题的解决时间。

***

<div id="3-what-causes-this-in-ssl-inspected-environments">
  ## 3. 在启用 SSL 检查的环境中问题产生的原因
</div>

当启用 SSL 检查时，网关会终止并重新建立 TLS 连接。客户端会看到一个由企业检查 CA (根 CA，有时还有中间 CA 证书) 签名的合成服务器证书。

Windsurf 的连接失败通常发生在以下情况：

* 终端设备上**未信任企业检查根 CA**，以及/或

* 检查证书的**链不完整** (缺少中间 CA) ，以及/或

* IDE/运行时使用的**非操作系统级信任存储**中未包含企业检查 CA 链，以及/或

* 企业策略强制执行的 TLS 约束导致 TLS 协商失败 (最低 TLS 版本/密码套件、阻止无法解密的流量等)

这通常是企业证书 / 信任 / 策略配置问题，而不是 Windsurf 本身实现的问题。

***

<div id="4-work-with-your-it-security-team-to-resolve">
  ## 4. 与公司 IT / 安全团队协作解决
</div>

由于 SSL 检查和证书部署由组织统一管理，通常需要 IT / 安全团队进行相关配置更改才能解决。

<div id="a-validate-ssl-inspection-policy-for-windsurf-traffic">
  ### A) 验证针对 Windsurf 流量的 SSL 检查策略
</div>

请与 IT/安全团队确认：

* SSL 检查是否适用于与 Windsurf 相关的出站 HTTPS 流量

* 是否存在由于证书验证、策略原因或 TLS 握手/协商限制而导致的任何拦截或拒绝

<div id="b-ensure-the-enterprise-inspection-ca-chain-is-correctly-deployed-and-trusted">
  ### B) 确保企业 SSL 检查 CA 证书链已正确部署并被信任
</div>

请让 IT/安全团队：

* 将企业 SSL 检查的 **Root CA** 部署到开发者终端设备

* 确保所有必要的 **Intermediate CA certificates** 已存在且证书链正确

* 使用与 IDE/运行时相同的信任存储 (操作系统证书库 vs 特定运行时证书库) 验证信任

<div id="c-configure-a-scoped-ssl-inspection-bypass-fallback">
  ### C) 配置限定范围的 SSL 检查绕过 (后备方案)
</div>

如果无法实现信任对齐，请让 IT/安全团队：

* 为所需的 Windsurf 服务端点创建 SSL 检查绕过 (按照贵组织的允许列表/网络需求流程)

* 将绕过范围尽量限定在必要的最小范围内，并与贵组织的安全策略保持一致

***

<div id="5-what-to-send-to-it-security-copypaste">
  ## 5. 需要发给 IT / 安全部门的内容 (复制/粘贴)
</div>

**问题：** Windsurf Editor 在公司网络上无法连接；很可能是 SSL 检查 / TLS 拦截导致的证书信任或证书链问题。

**证据：** 在 Help → Developer Tools → Console 中看到 TLS/证书或握手错误 (可展开查看红色的控制台错误条目) 。

**请求：**

1. 请确认是否对与 Windsurf 相关的出站 HTTPS 流量启用了 SSL 检查。

2. 请确认企业 SSL 检查的 Root CA 及任何中间证书已在此终端设备上部署并被信任 (以及在 IDE 所使用的任何特定运行时信任存储中) 。

3. 如果无法完成证书信任配置，请为所需的 Windsurf 服务端点配置限定范围的 SSL 检查绕过策略。

**请附上：**

* 故障发生的时间戳

* 操作系统版本

* 是否安装 / 启用了 Zscaler Client Connector (或类似代理)

* 在 Developer Tools → Console 中展开的详细控制台错误文本

* 是否在热点 / 家庭网络下可以正常使用，而在公司网络下失败

***

<div id="6-when-to-use-which-option">
  ## 6. 何时使用哪种选项
</div>

在以下情况下使用证书部署/信任修复：

* 错误提示为“unknown authority”、“unable to verify”、“issuer not found”或缺少中间证书

* 你希望在保持启用 SSL 检查的同时，获得最持久的修复效果

在以下情况下使用限定范围的 SSL 检查绕过：

* IDE/运行时在实际操作中无法使用企业 CA 链

* 你的环境中信任库 (trust store) 的一致性不可靠

* IT/安全团队确认检查导致了故障，并批准添加有针对性的例外规则

如果你不确定哪种情况适用，你的 IT/安全团队是最终权威来源——他们可以确认是否启用了 SSL 检查、使用了哪条 CA 链、如何管理端点，以及绕过规则是否合适。