官方教程中文版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