---
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="/zh-Hant/docs/cursor/official/07-help-troubleshooting/101-ai-features-overview" />
  <Card title="首個真實專案" description="把安裝驗收放進完整工作流" href="/zh-Hant/docs/cursor/understanding/12-real-project-workflow" />
  <Card title="索引與上下文" description="排查 Agent 找不到程式碼的問題" href="/zh-Hant/docs/cursor/official/07-help-troubleshooting/102-customization-help" />
</Cards>
