AI 编程教程中文版
官方教程中文版Help Center 与排障

Agent、Tab、网络和性能排障

把 Cursor Agent、Tab、安装启动、网络代理、SSH/VPN、扩展冲突和性能问题整理成一套分诊树。

这是 Cursor Help/Troubleshooting 的收束页：当用户只说“Cursor 不行”“Agent 乱改”“Tab 没了”“联网失败”“很卡”时，用它把问题拆成可验证的排障路径。

核验日期：2026-05-06。Agent、Tab、HTTP Compatibility Mode、网络诊断、扩展和性能建议会随客户端变化；排障前按官方 Help Center 复核。

1. 一句话判断

先不要重装。按顺序判断：是 Agent 上下文问题、Tab 服务问题、网络 streaming 问题、扩展冲突、版本/安装问题，还是机器资源问题。

同一个症状可能有不同根因。例如 “Agent 很慢” 可能是网络代理，也可能是索引、模型用量、远程 SSH、扩展或任务太大。

2. Agent 排障

Agent 不准确

官方建议：

  • prompt 要具体，包含 expected behavior 和 constraints。
  • 多文件任务先用 Plan mode。
  • 完成一个 feature 或切换任务时开新 chat。
  • 把稳定项目模式写进 .cursor/rules/。
  • 用 @file 或 @folder 给 Agent 定向上下文。

本地补充判断：

  • 如果 Agent 总找错文件，先查 indexing、ignore files、项目根目录是否打开正确。
  • 如果 Agent 总违反团队约束，先查 Rules、AGENTS.md、CLAUDE.md。
  • 如果 Agent 反复跑错命令，先查终端审批、hooks 和项目脚本。

Agent 找不到文件

按顺序查：

  1. .cursorignore 是否排除了目标文件。
  2. .gitignore 是否间接影响发现。
  3. 是否需要 Reindex。
  4. 是否可以用 @filename 直接附加文件。
  5. 是否打开了父目录或错误 workspace。

Agent 改坏了

官方说明可在历史消息右下角使用 Restore Checkpoint 回滚该点之后 Agent 做的改动。Checkpoint 存在本地，和 git 分开；长期版本控制仍然用 git。

Agent 终端行为异常

官方说明 Agent 执行 terminal commands 时会设置 CI=1，让工具输出更干净。如果项目在 CI=1 下行为不同，可在命令前取消它：

unset CI && your-command

也可以写进 project rule，提醒 Agent 对特定命令加前缀。

报告坏回复

官方要求：

  1. 点击回复底部的 ...。
  2. 选择 Copy Request ID。
  3. 到 forum.cursor.com 提供 request ID、复现步骤和 system info。
  4. system info 在 macOS 的 Cursor > About Cursor，Windows/Linux 的 Help > About。

3. Tab 排障

Tab 不出现

官方排查顺序：

  • Hobby 用户是否用完 monthly Tab allowance。
  • 企业网络是否阻断 HTTP/2。
  • Cursor 是否过旧，需要 Cursor: Attempt Update。
  • 设备是否断网。

如果网络阻断 HTTP/2，在 Cursor Settings 搜索 HTTP Compatibility Mode，切到 HTTP/1.1，并重启 Cursor。

Tab 质量差

Tab 基于 recent edits、cursor 周围代码和 linter errors。新文件或空文件上下文少，建议先手写几处意图明确的代码。

如果建议一直怪异，查：

  • 是否有其他 AI coding assistant extension。
  • 是否有快捷键冲突。
  • 当前文件类型是否应关闭 Tab。
  • Tab 是否被右下角 status indicator 暂停或按扩展名禁用。

Tab 很慢

先查：

  • 网络连接。
  • VPN / proxy 延迟。
  • 扩展冲突。
  • 是否需要更新 Cursor。

4. 网络、代理、SSH 和 VPN

网络诊断

官方入口：Cursor Settings > Network > Run Diagnostics。它会测试到 Cursor servers 的连接，定位影响 AI features 或 updates 的问题。

代理和 HTTP/2

Cursor 使用 HTTP/2 streaming。企业代理，尤其是部分 Zscaler 配置，可能阻断 HTTP/2。

用户侧临时处理：

  • Cursor Settings > Network。
  • HTTP Compatibility Mode 设为 HTTP/1.1。
  • 重启 Cursor。

企业侧要回到 86 页处理 allowlist、SSL inspection、SSE passthrough 和长连接。

需要放行的官方域名：

  • *.cursor.sh
  • *.cursor-cdn.com
  • *.cursorapi.com

SSH / remote connections

官方说明：使用 Cursor Remote SSH extension 时，AI requests 从本地机器发往 Cursor servers，不是从 remote host 发出。

排查顺序：

  • 本地网络是否正常。
  • remote server 是否 CPU 或内存耗尽。
  • SSH 是否频繁断开。
  • 断开后是否重启 Cursor，清理 stale processes。

如果 SSH 经常断，可增加 SSH keep-alive：

ServerAliveInterval 60
ServerAliveCountMax 3

VPN 和 DNS

VPN 断开后 Cursor 可能继承之前的 DNS 设置。AI features 或 agents 报 DNS errors 时：

  1. 完全退出并重启 Cursor。
  2. macOS 用 scutil --dns 检查系统 DNS。
  3. Linux 检查 /etc/resolv.conf。

Suspicious activity

官方说明该消息表示请求被安全措施阻断，VPN 有时会触发。先关 VPN；仍不行时开新 chat、等待几分钟，或换 Google/GitHub 认证方式登录。

5. 安装、扩展和性能

启动白屏或安装异常

官方建议：

  • 退出并重启 Cursor。
  • Mac：移到 Trash 后从 cursor.com/download 重装。
  • Windows：以 administrator 运行。
  • command palette 运行 Clear Editor History。
  • 更新时用 Cmd/Ctrl+Shift+P 搜索 Cursor: Attempt Update。

扩展冲突

官方排查：

  1. command palette 搜索 Disable All Installed Extensions。
  2. 看问题是否消失。
  3. 逐个重新启用扩展找冲突。

最常见冲突来源是其他 AI coding assistants，或会拦截快捷键的扩展。

性能差、CPU 或内存高

官方建议：

  • 禁用不需要的扩展。
  • 用 cursor --disable-extensions 测试无扩展模式。
  • 把 dist/、build/、.next/ 等 generated folders 加进 .cursorignore。
  • 确保 node_modules 等依赖目录在 .gitignore 中。

6. 一线支持分诊清单

每次接问题先收集：

  • Cursor version 和 OS。
  • 问题入口：Agent、Tab、network、SSH、VPN、extensions、performance、install。
  • 是否企业设备、是否代理、VPN、Zscaler、MDM。
  • 当前模型和账号计划。
  • 是否新 chat 复现。
  • 是否能在无扩展模式复现。
  • 是否能在非 VPN 网络复现。
  • request ID、截图、日志、terminal output。

7. 商业级验收

  • Agent 问题能区分上下文、规则、索引、终端、模型和网络。
  • Tab 问题能区分 allowance、HTTP/2、版本、网络和扩展。
  • 网络问题能跑 Run Diagnostics，并知道 HTTP Compatibility Mode。
  • SSH 问题知道 AI requests 从本地机器发出。
  • VPN/DNS 问题知道要完整重启 Cursor。
  • 扩展和性能问题能用禁用扩展方式复现。
  • 可转交问题包含 request ID 和 system info。

8. 常见失败点

  • 一上来重装，不先分诊。
  • Agent 不读文件时只改 prompt，不查 .cursorignore 和 indexing。
  • Tab 不出现时不看计划 allowance 和 HTTP compatibility。
  • 远程 SSH 出问题时误查 remote host 到 Cursor 的网络。
  • 代理缓冲 streaming，被误判成模型慢。
  • 扩展冲突没有用无扩展模式验证。

官方来源

接下来去哪

返回官方教程目录

继续按能力域查 Cursor 官方资料

安装与首项目

从第一天验收开始排查

网络配置

企业代理和 streaming 深入排查

账号与账单排障

把 Cursor billing cycle、included usage、on-demand、seat、invoice、payment、cancel、refund 整理成可转交的账务排障流程。

本页目录

1. 一句话判断2. Agent 排障Agent 不准确Agent 找不到文件Agent 改坏了Agent 终端行为异常报告坏回复3. Tab 排障Tab 不出现Tab 质量差Tab 很慢4. 网络、代理、SSH 和 VPN网络诊断代理和 HTTP/2SSH / remote connectionsVPN 和 DNSSuspicious activity5. 安装、扩展和性能启动白屏或安装异常扩展冲突性能差、CPU 或内存高6. 一线支持分诊清单7. 商业级验收8. 常见失败点官方来源接下来去哪