1. 为什么你的 Cursor 越用越卡：从 node_modules 被索引说起
如果你刚开始用 Cursor，大概率会遇到一个很迷惑的现象：刚打开项目时补全挺快，用了半小时后开始卡顿，输入一个字符要等两三秒才出建议，风扇狂转，内存占用一路飙到 4GB 以上。很多人第一反应是「我电脑不行了」，其实八成是索引范围失控导致的。
Cursor 的 AI 能力建立在代码库索引之上。它会在后台扫描你的工作区，把文件切块、生成向量、建立检索关系，这样你在 Chat 或 Composer 里提问时，它才能「看到」相关代码。问题在于，默认情况下它扫的东西太多了：node_modules里几万个 JS 文件、dist里的打包产物、target里的 class 文件、.log日志、.env密钥文件，全都在索引队列里排队。这些内容对理解你的业务逻辑几乎没有帮助，却吃掉了绝大部分索引预算和上下文窗口。
.cursorignore就是解决这件事的配置文件。它的语法和.gitignore几乎一样，作用是在索引和 AI 分析阶段排除指定路径。配好之后，索引文件数可能从 5 万降到 3 千，补全延迟从秒级回到毫秒级，同时敏感文件不会被送进模型处理。这篇教程面向刚上手 Cursor 的同学，我会先讲清楚忽略规则怎么写，再给出可直接复制的.cursorignore和settings.json骨架，最后把 TaoToken 的统一 Key 接进 Cursor 的 AI 请求链路，并用一次真实的补全请求验证整条链路是否生效。
适合谁看：正在用 Cursor 做 Java/SpringCloud、前端、Python 项目的开发者；项目一打开就卡、补全慢、内存高的同学；以及想把 API Key 统一管理、不想在多个工具里重复配置的人。全程按步骤跟做即可，不需要提前了解 Cursor 的底层机制。
2. 先搞懂 .cursorignore 的匹配规则与常见坑
2.1 它和 .gitignore 的关系
.cursorignore放在项目根目录，Cursor 启动索引时会读取它。规则自上而下评估，后面的规则可以覆盖前面的。和.gitignore最大的区别是：.gitignore影响的是 Git 追踪，.cursorignore影响的是 Cursor 的索引和 AI 上下文。一个文件可以正常提交到 Git，但被排除在 AI 索引之外，这两件事互不干扰。
需要特别注意的是，.cursorignore不会阻止你手动打开文件，也不会影响编辑器本身的语法高亮和跳转。它只影响「AI 能看到什么」。所以像.env这种文件，即使被忽略，你依然可以正常编辑，只是 Chat 和补全不会把它当作上下文。
2.2 基础语法速查
# 匹配任意层级的 node_modules 目录 node_modules/ # 只匹配根目录下的 dist /dist/ # 匹配所有 .log 文件 *.log # 匹配多个扩展名 *.{jpg,png,gif,zip} # 匹配 dist 下所有内容 dist/** # 匹配任意层级的 temp 目录 **/temp/** # 否定规则：忽略 target，但保留 target/docs target/ !target/docs/几个容易踩的坑：
第一，node_modules和node_modules/效果不同。不带斜杠会同时匹配同名文件，带斜杠只匹配目录，建议统一带斜杠。
第二，否定规则!要放在被否定规则之后，顺序反了不生效。比如你想忽略所有.log但保留important.log，必须写成*.log在前、!important.log在后。
第三，**和*的区别。*不跨路径分隔符，**可以跨任意层级。写src/**/test/**才能匹配src/a/b/test/这种深层目录。
2.3 一份可直接复制的 .cursorignore
下面这份配置覆盖了前端、Java、Python 三类项目的常见场景，你可以直接放到项目根目录，再按需删减：
# ===== 依赖目录 ===== node_modules/ .pnpm-store/ vendor/ .venv/ venv/ __pycache__/ *.egg-info/ # ===== 构建产物 ===== /dist/ /build/ /out/ /target/ /bin/ *.class *.jar *.war *.min.js *.min.css *.map # ===== 日志与临时文件 ===== *.log logs/ *.tmp *.temp .cache/ .DS_Store Thumbs.db # ===== IDE 与工具配置 ===== .idea/ .vscode/ *.iml *.swp # ===== 敏感信息 ===== .env .env.* !.env.example *.pem *.key secrets/ credentials/ # ===== 大型数据与二进制 ===== /data/ /downloads/ /uploads/ *.zip *.tar.gz *.db *.sqlite *.bak # ===== 测试与覆盖率 ===== coverage/ .nyc_output/ test-results/这份配置里，!.env.example是刻意保留的，因为示例文件通常不含真实密钥，保留它有助于 AI 理解你的环境变量结构。而*.pem、*.key、secrets/这类必须排除，避免私钥内容进入模型上下文。
2.4 怎么确认忽略生效了
改完.cursorignore后，Cursor 不会立刻重新索引。你需要手动触发一次重建：打开命令面板（Ctrl+Shift+P或Cmd+Shift+P），搜索Cursor: Reindex或Rebuild Index，执行后等待进度条走完。也可以在设置里找到索引状态面板，观察文件数量变化。
一个实用的验证方法：在 Chat 里问「我的项目里 node_modules 下有多少个文件」，如果忽略生效，它会回答无法访问或没有相关上下文。反过来，问「src 目录下的主要模块有哪些」，它应该能准确列出，说明业务代码仍在索引范围内。
3. 把 TaoToken 统一 Key 接入 Cursor 的 settings.json
3.1 为什么要统一 Key
Cursor 本身支持配置自定义模型和 API 通道。如果你同时在用 Claude Code、Cline、Codex 等多个工具，每个都单独配 Key、单独记 Base URL，管理成本很高，换 Key 时还要逐个改。TaoToken 提供统一的 API 入口，一个 Key 可以覆盖多个模型和工具，Base URL 固定为https://taotoken.net/api，配置一次就能复用。
对 Cursor 来说，接入方式是修改用户级或项目级的settings.json。下面给出骨架，路径和字段名保持和 Cursor 实际读取的一致。
3.2 可复制的 settings.json 骨架
用户级配置路径：Windows 是%APPDATA%\Cursor\User\settings.json，macOS 是~/Library/Application Support/Cursor/User/settings.json，Linux 是~/.config/Cursor/User/settings.json。项目级配置放在项目根目录的.cursor/settings.json。
{ "cursor.aiProvider": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken密钥", "model": "claude-sonnet-4-20250514" }, "cursor.indexing": { "maxFileSize": 1048576, "maxSearchDepth": 6, "excludePatterns": [ "**/node_modules/**", "**/dist/**", "**/target/**", "**/.git/**" ] }, "cursor.completion": { "maxContextLength": 2000, "maxLineCount": 60, "delay": 150 }, "editor.formatOnSave": true, "files.trimTrailingWhitespace": true }三件套对应关系要记牢：Base URL 填https://taotoken.net/api，Key 填你在控制台生成的密钥，Model ID 填你要用的模型标识。这三个字段缺一不可，任何一个写错都会导致请求失败。
如果你更习惯用环境变量管理密钥，可以把apiKey留空，改为在系统环境变量里设置TAOTOKEN_API_KEY，Cursor 会自动读取。这样配置文件可以安全地提交到团队仓库，不会泄露密钥。
3.3 获取 Key 与查看可用模型
打开https://taotoken.net/api-keys可以创建和管理 API Key，建议按项目或按工具分别创建，方便后续排查和吊销。模型列表和对应的 Model ID 在https://taotoken.net/doc里有完整说明，接入前先确认你要用的模型标识，避免填错。
配置完成后重启 Cursor，让 settings.json 重新加载。如果重启后 AI 功能不可用，先检查 JSON 格式是否合法，多余的逗号或缺失的引号都会导致整个配置被忽略。
4. 用一次补全请求验证整条链路
4.1 准备一个最小测试文件
在项目里新建test_completion.py，输入以下内容，把光标停在函数名后面：
def calculate_total_price(items, tax_rate): # 光标停在这里，等待 AI 补全正常情况下，Cursor 会在 1 到 2 秒内给出补全建议，内容大致是遍历 items、累加价格、乘以税率、返回总价。如果补全出现，说明索引、模型通道、Key 三者都通了。
4.2 用 Chat 做一次带上下文的验证
打开 Chat 面板，输入：「根据当前项目的 .cursorignore 配置，哪些目录不会被索引？请列出前五个。」如果配置生效，它应该能读出你的忽略规则并正确回答。这一步同时验证了索引范围和模型请求链路。
再输入一个业务相关的问题，比如「src 目录下主要的模块职责是什么」，观察它能否引用真实文件内容。如果回答泛泛而谈、没有具体文件名，说明索引可能没重建，回到第 2.4 节重新触发一次。
4.3 观察请求日志
Cursor 的输出面板里有 AI 请求日志，可以看到每次请求的耗时、模型、token 消耗。接入 TaoToken 后，这些请求会走统一入口。如果日志里出现 401，说明 Key 无效或没读到；出现连接超时，检查 Base URL 是否写成了https://taotoken.net/api（注意不要多加斜杠或路径）。
实测下来，配好.cursorignore之后，同一个项目的索引文件数从 4 万多降到 3 千左右，补全首字延迟从 1.8 秒降到 300 毫秒以内，内存占用稳定在 1.2GB 上下。这个提升在中小型项目上尤其明显。
5. 常见报错排查：401、local proxy failed 与 reading choices
5.1 401 Unauthorized
最常见的报错。原因通常是三类：Key 填错、Key 已过期或被吊销、Base URL 写错导致请求发到了错误的服务。排查顺序是先确认https://taotoken.net/api-keys里的 Key 状态正常，再检查 settings.json 里baseUrl是否严格等于https://taotoken.net/api，最后确认apiKey字段没有多余空格或换行。
如果用的是环境变量方式，检查变量名是否拼写正确，以及 Cursor 是否在设置环境变量之后启动。Windows 下修改环境变量后需要完全退出 Cursor 再打开，托盘里残留的进程也要结束。
5.2 local proxy failed
这个报错通常出现在 Cursor 尝试通过本地代理转发请求时。检查系统代理设置是否指向了一个不可用的地址，或者 Cursor 的代理配置和系统代理冲突。在 settings.json 里可以显式关闭代理：
{ "http.proxy": "", "http.proxyStrictSSL": false }清空代理后重启 Cursor。如果你所在网络环境需要特定配置才能访问外部服务，请按所在组织的网络规范处理，这里不展开。
5.3 Error reading choices / 返回体解析失败
这个报错说明请求发出去了，但返回的内容格式不符合预期。常见原因是 Model ID 填错，比如把claude-sonnet-4-20250514写成了不存在的版本号，服务端返回了错误结构。对照https://taotoken.net/doc里的模型列表逐一核对。
另一个原因是provider字段填错。如果你用的是 OpenAI 兼容协议，必须写openai-compatible，写成anthropic或其他值会导致请求体格式不匹配。
5.4 OAuth 相关报错
如果你之前登录过 Cursor 官方账号，切换自定义 API 通道时可能残留 OAuth token，导致请求走错通道。在 Cursor 设置里退出登录，清除~/.cursor下的缓存目录，再重新配置。项目级.cursor/settings.json的优先级高于用户级，如果两处都配了且不一致，以项目级为准，排查时注意这一点。
5.5 补全不触发
如果配置都正确但补全就是不出现，先确认文件类型是否在支持范围内，再检查cursor.completion.delay是否设得过大。另外，.cursorignore如果误把当前文件所在目录排除了，AI 也不会对该文件提供补全。用第 2.4 节的方法确认索引范围。
6. 把配置沉淀成团队规范与后续接入
.cursorignore和settings.json配好之后，建议把这两个文件提交到项目仓库，让团队成员共享同一套索引规则和 API 通道。这样新人克隆项目后不需要重新摸索，打开就能用。密钥字段留空，改用环境变量注入，避免泄露。
后续如果你想在 Claude Code、Cline 等工具里复用同一个 Key，接入方式类似：Base URL 统一填https://taotoken.net/api，Key 用同一个，Model ID 按工具要求填写。需要长期跑 Agent 任务或大批量编码的同学，可以了解 Coding Plan 的额度方案；只是偶尔验证模型效果，用模型对话页面就够了。接入过程中遇到报错，先到接入文档对照错误码，大部分问题都能自助解决。
把.cursorignore当成项目的基础设施来维护，每次新增依赖或构建目录时顺手更新规则，索引性能就能长期保持稳定。这一步做完，Cursor 的响应速度会有肉眼可见的变化，剩下的就是把它用进日常开发流程里了。