Cursor 故障排查

解决： ① 检查浏览器弹窗是否被拦截（地址栏右侧查看拦截提示）；② GitHub 国内可直连但可能较慢，等 20-30 秒，刷新后再试；③ 如果 GitHub 一直登不上去，换 Google 登录试试；④ Cmd+Shift+P 搜索 'Cursor: Sign Out' 先退出再重新登录；⑤ 企业网络可能拦截 GitHub OAuth——联系 IT 开通。

解决： 通常是 auth token 过期。Cmd+Shift+P → 'Cursor: Sign Out' → 完全退出 Cursor（含系统托盘）→ 重新打开 → 登录。如果频繁出现，在 Settings 中搜索 'session' 查看当前会话状态。

解决： 免费版每天有使用次数上限。用完会静默停止——没有明显提示。三种选择：① 等第二天自动重置；② 升级 Pro 解锁更多用量；③ Settings → Models 中填入自己的 API Key（免费版也可用自定义 Key）。

解决： ① 检查 Cursor 底部状态栏 AI 图标是否亮着——灰色表示未连接；② 按 Cmd+Shift+P → 'Cursor: Restart AI' 重启 AI 服务；③ Settings → 搜索 'cursor.enable' 确认 AI 功能未被关闭；④ 检查是否误装了多个 AI 扩展（Tabnine、CodeGeeX 等会冲突），禁用其他 AI 补全扩展后重启 Cursor。

解决： 三步排查：① Cmd+Shift+P → 'Developer: Show Running Extensions'——按 CPU 占用排序，禁用占 CPU 超 5% 且不用的扩展；② Settings → 搜索 'cursor.indexing.exclude'，把 node_modules、.next、dist、build 加进去；③ Settings → 搜索 'cursor.maxMemory'，如果机器内存 ≥ 16GB，可尝试调大分配值（默认自动，改成 8192 MB）。

解决： 项目文件太多或包含超大文件时索引可能卡住。① Cursor 右下角点击 'Indexing' 字样 → 暂停索引，手动 Resync Index；② 用 .cursorignore 排除图片、PDF、数据库文件等非代码内容（详见本站<a href='/articles/ai-security-compliance' style={{ color: 'var(--color-accent)' }}>安全配置文章</a>）；③ 如果卡死不动：Cmd+Shift+P → 'Developer: Reload Window' 强制重载。

解决： ① 检查网络延迟——Cursor 需要实时请求 AI 服务器，国内高峰时段较慢；② Settings → Models → 把默认模型从 Claude Opus 换成速度更快的模型（如 Claude Sonnet 或自定义 DeepSeek）；③ 打开的文件不宜超过 15 个标签页，过多上下文会拖慢每次补全请求；④ Settings → 搜索 'cursor.debounceDelay'，默认 200ms，可调到 100ms（但 Token 消耗更快）。

解决： ① 关闭不用的标签页（每个标签页持有独立上下文占用内存）；② 关掉不用的 Copilot/Composer 对话面板，长对话积累的上下文不释放；③ 定期用 Cmd+Shift+P → 'Developer: Reload Window' 释放累积的内存（项目中所有 AI 上下文会重置）；④ 如果经常超 4GB，配置 settings.json 中减小 'cursor.maxContextFiles' 限制每次上下文文件数。

解决： 这是最常见的使用问题。Composer 不会自动写入文件——它只是预览。你必须手动点击每一个文件的 Apply 按钮（或一键 Apply All）才算应用。修改不满意可用 Cmd+Z 批量撤销。另外注意：被 .gitignore 排除的文件可能在 Composer 中不受影响——不是 Bug。

解决： ① 确认你是在正常的用户终端里使用 Cursor，不要以管理员/root 运行；② 检查 Composer 或 Chat 的权限模式——Settings → 'Cursor: Terminal Approvals'，设为 'on-request'（手动确认）确保每次命令执行前你能看到；③ Windows 用户：确认 Git Bash 已安装并在 Cursor 终端设置中设为默认 Shell。

解决： Cursor 的规则系统需要重启 AI 会话才能识别新规则：① Cmd+Shift+P → 'Cursor: Restart AI'；② 如果改的是 globs 匹配规则，确认文件路径在 globs 范围内（用 **/*.ts 不是 src/*.ts）；③ 检查 YAML 属性头格式——description 和 globs 冒号后必须有空格，缩进必须用空格不能 Tab。

解决： ① Agent 模式需要单独开启——Settings → Features → Agent → Enable；② 在 Composer 中切换模式为 'Agent' 而非 'Normal'；③ Agent 的自动执行权限需要在 Settings 中独立配置 'Agent: Auto Execute'，不同模式（Normal vs Agent）的权限是分开管理的。

解决： Composer 的修改不一定一次完美。① Apply 之前仔细看每个文件的 diff——红色是删除、绿色是新增——如果改动涉及你不熟悉的部分，先手动审查；② Apply 后立刻运行 tsc/lint 检查类型和语法错误——有错在 Composer 中继续追问让它修复；③ 大改动分步 Apply——先 Apply 第一部分 → 测试 → 再 Apply 第二部分，一次全 Apply 如果出问题难以定位是哪部分造成的；④ 不确定的改动先 git stash 暂存，Apply 后测试通过再 commit。

解决： ① 检查 Composer 面板底部的 Terminal 标签——命令输出在那里显示而非聊天区；② 有些长时间命令（如 npm install）Agent 等待完成后才在聊天区总结结果——耐心等待，不要重复发指令；③ 如果命令执行完 Terminal 标签为空：可能报错了但 Agent 没有正确捕获——在 Composer 中追问 '刚才那个命令的输出是什么？报错了吗？'；④ Settings → Features → Agent → 'Terminal Output Capture' 确认已开启。

解决： ① 确认两台设备登录的是同一个 Cursor 账户（GitHub 或 Google 同一账号）；② Settings → Sync → 点击 'Check Sync Status' 查看最近同步时间和冲突文件数；③ 如果某台设备改了设置但另一台没过来：在那台设备上 Settings → Sync → 'Force Upload' → 等 1-2 分钟 → 另一台设备 'Force Download'。

解决： Cursor 基于 VS Code，绝大多数扩展可用，但个别扩展（尤其是深度依赖 VS Code 内部 API 的）可能不兼容。① 查看扩展的 GitHub Issues 搜索 'Cursor' 关键词；② 如扩展本身不更新了，在 Settings → Extensions 中搜索功能相似的替代扩展；③ 理论上所有 VS Code 扩展都可装，如果装了用不了——禁用再启用，重启 Cursor。仍不行只能在原版 VS Code 中装。

解决： ① 检查 API Key 完整无误（无多余空格或换行）；② DeepSeek 用户确认 API Key 在 platform.deepseek.com 后台状态为“有效”；③ 部分供应商的 Key 有有效期——检查是否过期；④ Settings → Models → 删除旧的 Key → 重新粘贴新 Key → Cmd+Shift+P → 'Cursor: Restart AI'。

解决： ① 检查所用 API 端点的可达性——浏览器访问 API 地址确认返回 200 而非超时；② DeepSeek 国内可直连，其他海外 API（OpenAI、Anthropic）需要代理——Settings 中搜索 'cursor.proxy'，配置代理地址（格式 http://127.0.0.1:7890）；③ 尝试把模型从 Opus 级别换成 Sonnet 级别，响应时间可缩短 3-5 倍。

解决： 不同模型的补全风格差异很大。① 代码补全场景建议用编码专用模型（如 Claude Sonnet、DeepSeek V4），不要用通用模型；② Settings → Features → 'Inline Completion' 和 'Chat Model' 可以分开配置——补全用速度快的模型，Chat/Composer 用推理强的模型；③ 如果差距大到不可接受，建议回到 Pro 订阅的内置模型——每月包含的模型质量和配额通常够用。