官方教程中文版Help Center 与排障
安装和第一个项目排障
按官方 Help Center 把 Cursor 安装、登录、打开项目、首个 Agent 任务和迁移问题整理成可执行排障路径。
这页用于第一天上手和一线支持分诊：Cursor 是否能安装、登录、打开项目、让 Agent 读到代码，并完成一个可回退的小改动。
核验日期：2026-05-06。下载入口、安装包、迁移文档和系统兼容性可能变化；正式 onboarding 前回到官方 Help Center 复核。
1. 一句话判断
安装成功不代表 Cursor 可用。真正的首日验收是：能打开真实项目、Agent 能理解代码、diff 能被审查、改动能撤回。
如果这四件事任意一项失败，先按本页收集证据，再进入后续 Agent、Tab、网络、账号或模型用量排障页。
2. 安装路径
官方安装步骤很短：
- 打开 cursor.com/download。
- 下载对应操作系统安装包。
- 打开下载文件。
- 按系统完成安装：
- Mac：拖到 Applications。
- Windows：运行安装器。
- Linux：用 package manager，或解压 AppImage / archive 后运行。
- 打开 Cursor。
- 按提示登录 Cursor account。
安装排障先收集这些信息：
- 操作系统和架构。
- 下载来源和安装包文件名。
- 是否企业设备、是否被 MDM 或安全软件阻断。
- 报错截图或安装日志。
- 是否能访问
cursor.com、认证页面和下载域名。
3. 第一个项目 smoke test
安装后不要直接让 Agent 改复杂功能。先做一个低风险 smoke test：
- 打开 Cursor。
- 点击 File > Open Folder。
- 选择一个已有项目文件夹。
- 用 Agent 面板发一个只读请求，例如“解释这个项目的入口文件和启动方式”。
- 再发一个小改动请求，例如“在 README 增加一行本地测试说明”。
- 在 diff view 审查改动。
- 测试 Restore Checkpoint 或手动撤回 diff。
官方说明 Agent 面板快捷键是：
- Mac：Cmd + I。
- Windows / Linux：Ctrl + I。
4. 上下文是否正常
首个项目中最常见的问题不是安装，而是 Agent 没拿到正确上下文。
检查顺序：
- Agent 能否自动找到相关文件。
- 输入
@后能否选择文件或目录。 - codebase indexing 是否完成。
.gitignore或.cursorignore是否把关键文件排除了。- 项目是否有
AGENTS.md、CLAUDE.md、.cursor/rules/这类规则。 - 企业设备是否被 Allowed Team IDs、Privacy Mode、代理或网络策略影响。
5. 从 VS Code 或 JetBrains 迁移
迁移时不要一次性把所有配置、扩展、规则和快捷键都搬过来。先分层：
- 项目可运行：依赖、环境变量、启动命令正常。
- 编辑器习惯：主题、快捷键、扩展、formatter。
- AI 上下文：Rules、AGENTS.md、索引、ignore files。
- 团队治理：SSO、SCIM、Privacy Mode、Allowed Extensions。
遇到迁移问题时先判断是编辑器兼容、扩展缺失、项目环境、还是 AI 上下文，而不是统一归因到 Cursor bug。
6. 可转交的问题报告
向团队支持或官方反馈前，至少准备：
- Cursor version。
- OS version。
- 账号类型：Individual、Team、Enterprise。
- 是否企业设备和 MDM。
- 问题入口：安装、登录、打开项目、Agent、Tab、索引、网络。
- 复现步骤。
- 期望结果和实际结果。
- 截图、日志、diff 或命令输出。
7. 商业级验收
- 新用户能完成安装、登录和打开项目。
- 首个 Agent 只读任务能找到相关文件。
- 首个小改动能在 diff view 审查。
- 用户知道如何 Restore Checkpoint 或撤回改动。
@file/@folder能补充上下文。- 迁移问题能分到 VS Code、JetBrains、扩展、规则、索引或企业策略。
- 证据足够让第二个人复现。
8. 常见失败点
- 只确认安装成功，没有验证 Agent 和 diff。
- 首个任务直接让 Agent 改生产逻辑，导致排障难度放大。
- 不看 indexing 和 ignore files，误判为 Agent 不懂项目。
- 把企业网络、账号、权限问题当成本地安装问题。
- 反馈问题时缺版本、系统、截图和复现步骤。
官方来源
- https://cursor.com/help/getting-started/install.md
- https://cursor.com/help/getting-started/first-project.md
- https://cursor.com/help/getting-started/migrate-vscode.md
- https://cursor.com/help/getting-started/migrate-jetbrains.md