---
title: "安装和第一个项目排障"
description: "按官方 Help Center 把 Cursor 安装、登录、打开项目、首个 Agent 任务和迁移问题整理成可执行排障路径。"
verifiedAt: "2026-05-09"
---
这页用于第一天上手和一线支持分诊：Cursor 是否能安装、登录、打开项目、让 Agent 读到代码，并完成一个可回退的小改动。

> [!NOTE]
> **核验日期**：2026-05-06。下载入口、安装包、迁移文档和系统兼容性可能变化；正式 onboarding 前回到官方 Help Center 复核。

## 1. 一句话判断

安装成功不代表 Cursor 可用。真正的首日验收是：能打开真实项目、Agent 能理解代码、diff 能被审查、改动能撤回。

如果这四件事任意一项失败，先按本页收集证据，再进入后续 Agent、Tab、网络、账号或模型用量排障页。

## 2. 安装路径

官方安装步骤很短：

1. 打开 [cursor.com/download](https://cursor.com/download)。
2. 下载对应操作系统安装包。
3. 打开下载文件。
4. 按系统完成安装：
   - Mac：拖到 Applications。
   - Windows：运行安装器。
   - Linux：用 package manager，或解压 AppImage / archive 后运行。
5. 打开 Cursor。
6. 按提示登录 Cursor account。

安装排障先收集这些信息：

- 操作系统和架构。
- 下载来源和安装包文件名。
- 是否企业设备、是否被 MDM 或安全软件阻断。
- 报错截图或安装日志。
- 是否能访问 `cursor.com`、认证页面和下载域名。

## 3. 第一个项目 smoke test

安装后不要直接让 Agent 改复杂功能。先做一个低风险 smoke test：

1. 打开 Cursor。
2. 点击 File > Open Folder。
3. 选择一个已有项目文件夹。
4. 用 Agent 面板发一个只读请求，例如“解释这个项目的入口文件和启动方式”。
5. 再发一个小改动请求，例如“在 README 增加一行本地测试说明”。
6. 在 diff view 审查改动。
7. 测试 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/install.md)
- [https://cursor.com/help/getting-started/first-project.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-vscode.md)
- [https://cursor.com/help/getting-started/migrate-jetbrains.md](https://cursor.com/help/getting-started/migrate-jetbrains.md)

## 接下来去哪

<Cards>
  <Card title="继续下一页" description="101-ai-features-overview" href="/docs/cursor/official/07-help-troubleshooting/101-ai-features-overview" />
  <Card title="首个真实项目" description="把安装验收放进完整工作流" href="/docs/cursor/understanding/12-real-project-workflow" />
  <Card title="索引与上下文" description="排查 Agent 找不到代码的问题" href="/docs/cursor/official/07-help-troubleshooting/102-customization-help" />
</Cards>
