跳转到主要内容
某些企业或公司网络会对出站 HTTPS 流量执行 TLS 拦截 (“SSL 检查”) (通常通过 Zscaler 或类似安全网关) 。Windsurf Editor 必须与外部服务建立出站 TLS 连接 (用于登录和依赖云端的功能) 。如果被检查的流量被企业检查 CA 重新签名，而你的机器或运行时并不信任该 CA (或证书链不完整) ，Windsurf 可能会因 SSL/证书或协商错误而无法连接。 在以下情况下，可能需要排查 SSL/TLS 检查问题：
  • 你看到 “Failed to connect (连接失败) ” 或类似网络错误
  • 编辑器或 Cascade 面板显示空白屏幕且始终无法加载
  • Cascade 或其他依赖云端的功能无法加载或连接
  • 登录或激活流程意外失败
  • 在热点/家庭网络下功能正常，但在公司网络下失败
  • 在日志或开发者工具 (devtools) 中看到证书或 TLS 握手错误
如果你同时遇到代理相关问题，请参见 Proxy Configuration (代理配置) 。

​
1. 检查你的网络是否使用 SSL 检查

在更改编辑器中的任何设置之前，先询问你的 IT / 安全 / 网络团队：
  • 我们是否对出站 HTTPS 流量执行 TLS 拦截 / SSL 检查？
  • 是否对开发者工作站和开发者工具 (不仅仅是浏览器) 启用了 SSL 检查？
  • 对被检查的流量签名使用的是哪条 Root CA / Intermediate CA 证书链？
  • 该 CA 证书链是否已部署到各终端，并被开发所用的应用程序 / 运行时信任？
如果你的组织不使用 SSL 检查，通常不需要参考本指南。如果你的组织使用 SSL 检查，请继续阅读下面的内容。

​
2. 在 Windsurf 中捕获底层错误 (Developer Tools → Console)

基于 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/安全团队，通常可以显著缩短问题的解决时间。

​
3. 在启用 SSL 检查的环境中问题产生的原因

当启用 SSL 检查时，网关会终止并重新建立 TLS 连接。客户端会看到一个由企业检查 CA (根 CA，有时还有中间 CA 证书) 签名的合成服务器证书。 Windsurf 的连接失败通常发生在以下情况：
  • 终端设备上未信任企业检查根 CA，以及/或
  • 检查证书的链不完整 (缺少中间 CA) ，以及/或
  • IDE/运行时使用的非操作系统级信任存储中未包含企业检查 CA 链，以及/或
  • 企业策略强制执行的 TLS 约束导致 TLS 协商失败 (最低 TLS 版本/密码套件、阻止无法解密的流量等)
这通常是企业证书 / 信任 / 策略配置问题，而不是 Windsurf 本身实现的问题。

​
4. 与公司 IT / 安全团队协作解决

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

​
A) 验证针对 Windsurf 流量的 SSL 检查策略

请与 IT/安全团队确认：
  • SSL 检查是否适用于与 Windsurf 相关的出站 HTTPS 流量
  • 是否存在由于证书验证、策略原因或 TLS 握手/协商限制而导致的任何拦截或拒绝

​
B) 确保企业 SSL 检查 CA 证书链已正确部署并被信任

请让 IT/安全团队：
  • 将企业 SSL 检查的 Root CA 部署到开发者终端设备
  • 确保所有必要的 Intermediate CA certificates 已存在且证书链正确
  • 使用与 IDE/运行时相同的信任存储 (操作系统证书库 vs 特定运行时证书库) 验证信任

​
C) 配置限定范围的 SSL 检查绕过 (后备方案)

如果无法实现信任对齐，请让 IT/安全团队：
  • 为所需的 Windsurf 服务端点创建 SSL 检查绕过 (按照贵组织的允许列表/网络需求流程)
  • 将绕过范围尽量限定在必要的最小范围内，并与贵组织的安全策略保持一致

​
5. 需要发给 IT / 安全部门的内容 (复制/粘贴)

问题： 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 中展开的详细控制台错误文本
  • 是否在热点 / 家庭网络下可以正常使用，而在公司网络下失败

​
6. 何时使用哪种选项

在以下情况下使用证书部署/信任修复：
  • 错误提示为“unknown authority”、“unable to verify”、“issuer not found”或缺少中间证书
  • 你希望在保持启用 SSL 检查的同时，获得最持久的修复效果
在以下情况下使用限定范围的 SSL 检查绕过：
  • IDE/运行时在实际操作中无法使用企业 CA 链
  • 你的环境中信任库 (trust store) 的一致性不可靠
  • IT/安全团队确认检查导致了故障，并批准添加有针对性的例外规则
如果你不确定哪种情况适用，你的 IT/安全团队是最终权威来源——他们可以确认是否启用了 SSL 检查、使用了哪条 CA 链、如何管理端点，以及绕过规则是否合适。