29 · 设置与配置

Cursor 基于 VS Code，但远不止 VS Code。它多出来的那一层 AI 能力——模型选择、Tab 补全、代码库索引、隐私策略——全都藏在 settings.json 和各种配置界面背后。不理解这些配置，你就只能用到 Cursor 50% 的能力。本章带你完整走通从 UI 到 JSON 的每一个配置开关。

01 · settings.json 探秘 —— Cursor 配置的基石

如果你是 VS Code 老用户，对 settings.json 一定不陌生：它是编辑器的”宪法文件”，控制着从字体大小到格式化规则的一切。Cursor 完全继承了这一机制，并在其上叠加了自己的专属配置层。

如何打开 settings.json

在 Cursor 中有四种方式打开全局设置文件：

文件结构速览

一个典型的 Cursor settings.json 包含三个层次：

{
  // === VS Code 原生设置 ===
  "editor.fontSize": 14,
  "editor.formatOnSave": true,
  "files.autoSave": "onFocusChange",
 
  // === Cursor 专属 AI 设置 ===
  "cursor.chat.model": "claude-sonnet-4-20250514",
  "cursor.composer.model": "claude-sonnet-4-20250514",
  "cursor.tabCompletion.enabled": true,
 
  // === 扩展引入的设置 ===
  "eslint.validate": ["javascript", "typescript", "typescriptreact"]
}

心法模型：把 settings.json 想象成一辆赛车的控制系统——VS Code 原生设置是底盘和悬挂（基础体验），Cursor 专属设置是发动机和涡轮（AI 动力），扩展设置是各种传感器和仪表盘。三个层次协同工作，任何一个出问题都会影响整体驾驶体验。

02 · 三层面设置体系：项目 vs 用户 vs 全局

Cursor 的设置体系沿用了 VS Code 的三层级优先模型，并针对 AI 配置做了扩展。理解这三个层级，是解决”为什么我的设置不生效”这类问题的第一步。

层级结构

注意：项目级的 Cursor 设置通常放在 .cursor/settings.json 而不是 .vscode/settings.json。前者是 Cursor 推荐的路径，后者会被 VS Code 兼容层读取。

实际场景演示

假设你有三段配置：

全局 settings.json：

{
  "cursor.chat.model": "claude-sonnet-4-20250514",
  "editor.fontSize": 14,
  "cursor.indexing.enabled": true
}

项目 .cursor/settings.json：

{
  "cursor.chat.model": "gpt-4o",
  "editor.fontSize": 16
}

生效结果：

• cursor.chat.model → gpt-4o（项目覆盖全局）
• editor.fontSize → 16（项目覆盖全局）
• cursor.indexing.enabled → true（项目未定义，继承全局）

何时使用项目设置

以下场景强烈建议使用项目级 .cursor/settings.json：

1. 团队项目统一 AI 模型：确保所有人使用同一模型，避免”在我电脑上是好的”
2. 配置索引范围：不同项目有不同的代码库大小，索引的包含/排除路径应该按项目设置
3. 私有模式按项目开启：敏感项目强制隐私模式，开源项目无所谓
4. 规则文件路径：cursor.rules 相关配置通常定义在项目级

03 · AI 模型配置 —— 选择你的编程引擎

模型配置是 Cursor 中最关键的一组设置。它直接决定了 AI 回答的质量、速度和成本。

核心模型配置项

{
  // Chat 对话使用的模型
  "cursor.chat.model": "claude-sonnet-4-20250514",
 
  // Composer / Agent 使用的模型
  "cursor.composer.model": "claude-sonnet-4-20250514",
 
  // 快速问答使用的轻量模型（如 Cmd+K 快速编辑）
  "cursor.fastCompletions": true,
 
  // 是否在 Chat 中启用 Agent 模式
  "chat.agent.enabled": true,
 
  // Agent 模式的最大请求轮次
  "cursor.chat.agent.maxRequests": 25
}

模型推荐配置表

心法模型：模型选择 = 工具选择

把模型选择想象成你去厨房做菜：

• Claude Sonnet 是你的主厨刀——90% 的场景都用它，顺手、锋利、不贵
• GPT-4o 是多功能料理机——切菜打蛋绞肉都能干，但每次用完后清洗（成本）你掂量掂量
• Claude Opus 是低温慢煮机——做复杂菜式时不可替代，但不会有人天天用它煎鸡蛋
• 本地模型（Ollama）是野炊的柴火灶——免费但火候难控、还要自己添柴

常见问题

Q：为什么我设置了模型但 Cursor 仍然在用别的模型？ A：检查两件事：1) 项目级 .cursor/settings.json 是否覆盖了全局设置；2) UI 设置面板中的”模型选择”下拉框——UI 选择会临时覆盖 settings.json 中的值，直到你点 “Reset” 才能恢复。

Q：Chat 和 Composer 可以使用不同模型吗？ A：可以。通过 cursor.chat.model 和 cursor.composer.model 分别设置。很多人 Chat 用 Sonnet（速度快），Composer 用 Opus（生成质量高）。

04 · Tab 补全配置详解

Tab 补全（Tab Autocomplete）是 Cursor 最”渗透感”的功能——你几乎感觉不到它的存在，但它每天都在替你打无数行代码。配置得当与否，直接影响编码流畅度。

关键配置项

{
  // [核心] 是否启用 Tab 补全
  "cursor.tabCompletion.enabled": true,
 
  // [核心] Tab 补全的延迟时间（毫秒）
  "cursor.tabCompletion.debounceMs": 50,
 
  // 补全触发的字符数阈值
  "cursor.tabCompletion.minChars": 1,
 
  // 是否显示多行补全
  "cursor.tabCompletion.multiline": true,
 
  // 补全后缀匹配
  "cursor.tabCompletion.suffixMatching": true,
 
  // 是否在补全时显示 diff 标记
  "editor.cursorSurroundingLines": 8,
 
  // 补全使用 GPU 加速（实验性）
  "cursor.tabCompletion.gpuAcceleration": false
}

各参数调优指南

debounceMs（去抖延迟）

• 默认值：50ms
• 调大（如 100-200ms）：适合机器性能较弱或电池模式下，减少补全频率换取续航
• 调小（如 10-20ms）：适合高性能机器，追求极致流畅感。但如果太低可能导致 CPU 占用高
• 建议：M 系列芯片 Mac 保持默认 50ms；Intel Mac 或低配 PC 可调至 80-100ms

minChars（最小触发字符数）

• 默认值：1
• 调大（如 3-5）：减少低频次干扰性补全，适合有经验的开发者
• 建议：新手保持 1，经验丰富后可调至 2 来减少”噪音”

multiline（多行补全）

• 开启后，Tab 补全不仅能补单个单词或表达式，还能补完整行甚至多行代码块
• 建议始终开启 —— 这是 Cursor 区别于普通 AI 补全的核心优势

Tab 补全常见误配置

05 · 隐私与安全配置

对于企业用户和安全敏感的个人开发者，隐私配置是重中之重。Cursor 在这方面的设置分布在三个位置。

隐私模式开关

{
  // [核心] 隐私模式 — 开启后数据不用于模型训练
  "cursor.privacy.enabled": true,
  // 可选：strict / flexible
  "cursor.privacy.mode": "strict",
 
  // 禁用遥测数据上报
  "cursor.telemetry.diagnostics": false,
  "cursor.telemetry.enabled": false,
 
  // 禁用漏洞扫描中的外部请求
  "cursor.securityVulnerabilityScanner": false
}

数据保留策略

工作区信任与权限配置

{
  // 工作区信任
  "security.workspace.trust.enabled": true,
 
  // 是否允许 AI 在项目中执行命令
  "cursor.composer.commandUse": "allow",
 
  // 是否允许 AI 读取终端输出
  "cursor.terminal.useLocal": true,
 
  // 自动运行命令的白名单
  "cursor.allowedCommands": ["npm", "yarn", "pnpm", "git", "node"]
}

心法模型：隐私设置 = 你的数据围栏

想象你在一片草地上露营。Cursor 默认情况下，AI 模型会在你写的代码上”学习”（就像营地周围可以走来走去的路人）。开启隐私模式，相当于拉起一圈围栏——AI 可以在围栏内帮你干活，但它看不见的东西不会传出去。

strict 模式是双层围栏加电网，flexible 是单层木栅栏。选哪个取决于你露营的地方是自家后院还是国家机密基地。

06 · 代码库索引配置

代码库索引（Codebase Indexing）是 Cursor 理解你整个项目结构的能力来源。没有正确的索引配置，@Codebase、@Files、跨文件重构等功能都会大打折扣。

核心索引设置

{
  // [核心] 是否启用代码库索引
  "cursor.indexing.enabled": true,
 
  // 索引包含的范围（默认自动检测）
  "cursor.indexing.include": ["src/**", "lib/**", "packages/**"],
 
  // 索引排除的范围
  "cursor.indexing.exclude": [
    "node_modules/**",
    "dist/**",
    "build/**",
    ".git/**",
    "coverage/**",
    "vendor/**"
  ],
 
  // 是否启用语义搜索（基于向量）
  "cursor.pinecone.enabled": true,
 
  // 全局搜索索引
  "cursor.enableGlobalSearchIndexing": false,
 
  // 索引的最大文件大小（KB）
  "cursor.indexing.maxFileSize": 500
}

索引配置策略

小型项目（< 10,000 文件）

• 保持默认配置即可
• 无需手动指定 include/exclude

中型项目（10,000 - 50,000 文件）

• 明确指定 include 路径聚焦核心源码
• 增大 maxFileSize 到 1000（1MB）
• 排除所有生成目录

大型项目（> 50,000 文件）

• 必须在 .cursorignore 中排除非必要目录
• 考虑按模块拆分索引范围
• 打开 enableGlobalSearchIndexing: false 避免索引膨胀

.cursorignore 文件

除了 settings.json 中的 exclude，你还可以在项目根目录创建 .cursorignore 文件，语法与 .gitignore 完全一致：

# .cursorignore
node_modules/
dist/
build/
*.min.js
*.bundle.js
coverage/
vendor/
*.generated.*

优先级：.cursorignore 中的规则 > cursor.indexing.exclude > cursor.indexing.include

07 · 设置同步机制

当你有多台开发机器（办公室 iMac + 家里 MacBook Pro），或者跟同事共享配置时，设置同步是必须掌握的技能。

Cursor 内置同步（Cursor Sync）

Cursor 提供了基于账号的官方设置同步服务：

{
  // 启用设置同步
  "cursor.sync.enabled": true,
 
  // 同步的配置项范围
  "cursor.sync.settings": true,
  "cursor.sync.keybindings": true,
  "cursor.sync.extensions": true,
  "cursor.sync.notepads": true,
  "cursor.sync.rules": true,
 
  // 同步的 UI 状态
  "cursor.sync.uiState": true
}

开启后，以下内容会在登录同一账号的多个设备间同步：

VS Code Settings Sync 兼容

如果你之前使用 VS Code 的 Settings Sync（通过 GitHub 账号同步），Cursor 也兼容这套机制。但建议优先使用 Cursor 自己的同步，因为它还同步了 Notepads 和 Rules 等 Cursor 特有项，这是 VS Code 的同步方案无法覆盖的。

手动同步策略

如果不想用云端同步（比如安全策略不允许），可以使用手动方式：

# 将当前配置导出备份
cp ~/Library/Application\ Support/Cursor/User/settings.json ~/cursor-backup/settings.json
cp ~/Library/Application\ Support/Cursor/User/keybindings.json ~/cursor-backup/
 
# 还原到新机器
cp ~/cursor-backup/settings.json ~/Library/Application\ Support/Cursor/User/

你也可以将配置文件纳入 Git 仓库管理：

cursor-config/
├── settings.json
├── keybindings.json
├── snippets/
└── README.md

08 · 关键配置项速查表

以下表格整理了你最可能用到的 30 个配置项，按功能分组，方便快速查阅。

AI 与模型

Tab 补全

代码库索引

隐私与安全

界面与行为

09 · 常见错误配置与避坑指南

从社区反馈和实际使用中，我们总结了一些最常见的配置问题。下面是 “雷区地图”，帮你少走弯路。

陷阱 #1：多个 AI 补全工具同时运行

// ❌ 错误 —— 同时启用了多个 AI 补全
{
  "cursor.tabCompletion.enabled": true,
  "github.copilot.enable": true,       // Copilot 也会抢着补全
  "tabnine.enabled": true              // TabNine 也在跑
}

后果：编辑器中出现多个重叠的补全建议，Tab 键不知道该听谁的，编辑器响应变慢。

解决方案：只保留 Cursor 的补全，禁用其他所有 AI 补全扩展。

// ✅ 正确
{
  "cursor.tabCompletion.enabled": true,
  "github.copilot.enable": false,
  "tabnine.enabled": false,
  "continue.enabled": false
}

陷阱 #2：项目设置中意外覆盖了全局 AI 模型

// 项目 .cursor/settings.json
// ❌ 错误的"锁定"行为
{
  "cursor.chat.model": "gpt-4o-2024-08-06"
}

后果：即使你在 UI 中切换成 Claude Sonnet，项目一打开又跳回 GPT-4o。因为项目级设置优先级高于 UI 选择。

解决方案：如果需要允许开发者自由选择模型，不要在项目级设置 cursor.chat.model。如果必须统一，结合 Team Rules 而非 settings.json 来施加约束。

陷阱 #3：索引范围过大导致内存爆炸

// ❌ 错误 —— 未配置 exclude
{
  "cursor.indexing.enabled": true
  // 缺少 exclude 配置！
}

后果：node_modules、.next、build 等目录被全量索引。项目稍大一点（30,000+ 文件），Cursor 会吃掉数 GB 内存，甚至崩溃。

解决方案：始终在项目 .cursor/settings.json 中配置 exclude，或创建 .cursorignore 文件。

陷阱 #4：隐私模式未开启就提交敏感代码

这个问题太常见了——开发者拿到了企业账号，但个人设备上的 Cursor 仍然是默认配置（隐私关闭）。在个人项目上没什么，但如果在企业项目里没开启隐私模式，你的代码可能被用于模型训练。

解决方案：在项目级配置中强制开启隐私模式：

// 项目 .cursor/settings.json
{
  "cursor.privacy.enabled": true,
  "cursor.privacy.mode": "strict"
}

陷阱 #5：错误的 JSON 语法导致设置不生效

// ❌ 错误 —— 末尾多了一个逗号
{
  "cursor.chat.model": "claude-sonnet-4-20250514",
  "cursor.tabCompletion.enabled": true,  // ← 这是 JSON 的语法错误！
}

JSON 不像 JavaScript，不允许末尾逗号（trailing comma）。一个多余的逗号会导致整个 settings.json 无法解析，所有设置回退到默认值。

解决方案：使用 Cmd+Shift+P → >Format Document 来格式化 settings.json，或者使用 VS Code 的 JSON 校验插件。Visual Editor 中的设置面板可以避免这个问题——它帮你生成合法的 JSON。

陷阱 #6：多台设备配置不一致

在办公室用 Mac，回家用 Windows，两边的 settings.json 不同步。结果就是：在 Mac 上好用的 Tab 补全频率，到 Windows 上变得迟缓或过于激进。

解决方案：启用 Cursor Sync（见第 07 节）或者将配置文件纳入 Git 管理。

10 · 总结

Cursor 的设置体系，说复杂也复杂——三层优先级、数十个 AI 专属配置项、JSON 语法陷阱——但说简单也简单，你只需要记住一条核心原则：

全局定基调，项目定策略，UI 定临时。

• 你个人的偏好（字体、模型偏好、快捷键）放在 全局 settings.json
• 团队的强制约定（隐私模式、索引范围、规则路径）放在 项目 .cursor/settings.json
• 临时的模型切换、功能开关，直接用 UI 面板操作

最后，送你一个检查清单，在新项目上手 Cursor 时过一遍：

1. 是否创建了 .cursor/settings.json？
2. 是否配置了索引的 exclude 或 .cursorignore？
3. 是否确认了隐私模式状态？
4. AI 模型选择是否符合项目需求？
5. 多台开发机的设置是否同步？
6. JSON 文件语法是否合法？

做好这六项检查，你的 Cursor 配置就不会出大问题。真正需要关注的，不是 “哪个设置改了什么”，而是 “这一组配置共同塑造了怎样的 AI 编程体验”。配置不是为了配置而配置，是为了让 AI 在正确的时间、用正确的方式、做正确的事。

下一篇：[30 · 代码库索引] —— 深入 Cursor 的代码库索引机制，理解向量搜索与语义索引的工作原理，让 AI 真正”看懂”你的项目。