---
title: "帮助与排障"
description: "帮助与排障相关的 Cursor 官方教程中文版。"
verifiedAt: "2026-05-09"
---

当 Cursor 行为和预期不一致时，先分层定位：账号、网络、项目索引、模型用量、工具权限、编辑器状态还是云端任务。这一组是 Cursor 的排障层——Help Center、故障页、网络页、Agent Tab、账号计费和模型用量页用来定位真实问题。

> [!NOTE]
> **阅读方式**：先看判断和路径，再进入具体章节。Cursor 的资料变化很快，模型、价格、用量和企业策略以官方页面为准。

<Cards>
  <Card title="安装和第一个项目排障" description="Help Center 中的安装、第一项目、迁移入口。" href="/docs/cursor/official/07-help-troubleshooting/100-install-first-project" />
  <Card title="AI Features Help" description="Agent、Ask、Plan、Debug、Tab、Inline Edit 等功能入口。" href="/docs/cursor/official/07-help-troubleshooting/101-ai-features-overview" />
  <Card title="Customization Help" description="Rules、Context、MCP、Skills、Indexing、Ignore files。" href="/docs/cursor/official/07-help-troubleshooting/102-customization-help" />
  <Card title="Models and Usage Help" description="模型、API keys、usage limits、token rate。" href="/docs/cursor/official/07-help-troubleshooting/103-models-usage-help" />
  <Card title="Security and Privacy Help" description="隐私、区域、合规、SSO、Marketplace security。" href="/docs/cursor/official/07-help-troubleshooting/104-security-privacy-help" />
  <Card title="Account and Billing Help" description="账单、发票、超额、支付、取消和退款。" href="/docs/cursor/official/07-help-troubleshooting/105-account-billing-help" />
  <Card title="Agent、Tab、网络和性能排障" description="常见 Agent、Tab、安装、网络、扩展和性能问题。" href="/docs/cursor/official/07-help-troubleshooting/106-troubleshooting-agent-tab-network" />
</Cards>

## 排障顺序

Cursor 出问题时，不要直接重装。先按层定位：

1. 账号和计费：是否登录、是否有用量、是否触发 limits。
2. 网络：企业代理、VPN、防火墙、DNS 是否拦截。
3. 项目索引：`.cursorignore`、`.gitignore`、semantic search、Reindex 是否影响文件发现。
4. Agent 上下文：prompt 是否具体，是否使用 Plan Mode，是否用 `@file` 指定文件。
5. 工具权限：terminal、browser、MCP、extensions 是否被限制。
6. 云端任务：Cloud Agent、Bugbot、Slack 或 GitHub 是否选错 repo/branch。
7. 性能：远程连接、本地资源、扩展冲突和缓存。

这个顺序能避免把网络问题误判成模型问题，也能避免把 `.cursorignore` 导致的上下文缺失误判成 Agent “不聪明”。

## 官方排障要点

官方 Help Center 里有几个高频事实：

- Agent 准确性依赖具体 prompt、Plan Mode、Rules 和 `@` 文件上下文。
- Agent 找不到文件时，先查 `.cursorignore` 和 `.gitignore`，再 Reindex 或直接 attach 文件。
- Agent 修改可以用 Restore Checkpoint 回退，但 checkpoint 是本地机制，不能替代 git。
- Agent terminal 默认可能带 `CI=1`，如果项目行为受影响，可以在命令前 unset。
- 企业代理或 VPN 拦截 HTTP/2 时，可以在 Network 设置里启用 HTTP Compatibility Mode 到 HTTP/1.1。
- 防火墙环境要 allowlist Cursor 相关域名。
- Remote SSH 场景下 AI 请求通常从本机发出，不是从远端主机发出。

这些都是排障时应该先确认的事实，不要靠猜。

## 提交问题的材料

如果要向团队或官方求助，至少收集：

- Cursor 版本和系统信息。
- Request ID 或相关任务 ID。
- 复现步骤。
- 期望行为和实际行为。
- 是否使用代理、VPN、Remote SSH、WSL 或企业网络。
- 相关 `.cursorignore`、Rules、MCP、terminal command。
- 已经尝试过的操作，例如 Reindex、HTTP/1.1 compatibility、restart。

材料越结构化，越容易判断是账号、网络、索引、Agent、工具还是云端任务问题。

## 不建议的做法

- 一出错就重装编辑器。
- 把所有规则删掉再试，导致真实边界丢失。
- 把企业代理绕开，用个人网络验证生产项目。
- 不看 Request ID 就把错误描述成“AI 不工作”。
- 没保留失败命令和日志就让 Agent 修自己。

排障页的目标是缩小问题面，而不是列所有可能原因。

## 官方来源

- [Cursor Docs](https://cursor.com/docs)
- [Cursor llms.txt](https://cursor.com/llms.txt)
- [Cursor Help Center](https://cursor.com/help)
- [Cursor Agent troubleshooting](https://cursor.com/help/troubleshooting/agent-issues.md)
- [Cursor Network, proxy, and remote connections](https://cursor.com/help/troubleshooting/network.md)
- [Cursor Performance troubleshooting](https://cursor.com/help/troubleshooting/performance.md)
