.cursorignore 不生效：忽略规则的作用范围与优先级

2026-08-18

先把两种”不生效”分开，它们的排查路径完全不同。

一种是该挡的没挡住：.cursorignore 里明明写了 .env*，对话里却还是出现了里面的值。另一种是不该挡的挡住了：某个文件没写进忽略规则，Agent 却说找不到它。第二种通常不是 .cursorignore 的锅，后面会讲。

这篇只谈忽略规则本身的语义边界。至于索引卡住、索引进度不动那类问题，我们另有一篇专门讲，这里不重复。

它到底管什么：三处官方口径放在一起看

Cursor 官方文档里，.cursorignore 的作用范围被写在三个不同页面上，措辞不完全一致，这是很多人误判的起点。

cursor.com/help/customization/ignore-files 写明：被忽略的文件”blocked from indexing and Agent”，紧接着补了一句——“Terminal commands and MCP tools run outside of Cursor’s file access controls, so they may still be able to read ignored files”。
cursor.com/help/troubleshooting/agent-issues 写得更细：写进 .cursorignore 的文件”blocked from Agent, codebase search, and @ mentions”。
cursor.com/docs/enterprise/llm-safety-and-controls 列的是两条：Agent file reading、Context selection；同一页还写了一句”It doesn’t prevent file access, only excludes from indexing”。

把这三处叠起来看，能确定的交集是：索引、Agent 的文件读取、代码库搜索、@ 提及，以及进入上下文的挑选环节。而企业页那句”只排除索引、不阻止文件访问”和帮助页那句”blocked from indexing and Agent”字面上并不一致——遇到这种口径差，稳妥的做法是按更保守的那一条规划，也就是别把它当访问控制用。

这不是我们的推测。企业页自己把话说死了：.cursorignore is not a security boundary，它是”a convenience feature to exclude files from AI processing”，并列出三条限制：用户可以手工打开被忽略的文件、Agent 可能找到别的路径拿到内容、它不阻止文件访问。同一页给出的替代方案是文件系统权限或加密（“For true security, use file system permissions or encrypt sensitive data”）。

cursor.com/docs/enterprise/security-hardening 的控制项表格里那一行也是同样口径：.cursorignore 用来”Block agent read and context for secrets and regulated trees”，但”terminal and MCP tools can’t honor it”，所以要配合审批与文件权限。同页在开头把这类控制分成两类：Auto-review、allowlist、.cursorignore 属于 best-effort，审批、hooks、sandboxing 属于 deterministic，建议分层叠加而不是只押一层。

优先级：哪几层规则同时在起作用

从文档能核到的层叠关系有这么几条：

.gitignore 是被自动遵守的。帮助页写明 Cursor 会遵守 .gitignore，被 git 忽略的文件同样被 Cursor 的索引忽略，而 .cursorignore 是”for additional exclusions beyond what .gitignore covers”——它是加法，文档没有把它描述成能覆盖 .gitignore 的那一层。所以如果你的诉求反过来——想让某个被 .gitignore 挡住的文件重新进入 Agent 视野——.cursorignore 这一页并没有说明它能做到这件事，官方参考页 cursor.com/docs/reference/ignore-file 里的语法细节不在我们整理的落盘范围内，具体以官方原文为准。

还有一批默认项不需要你写。帮助页写明 Cursor 默认已经忽略 .env 文件、.git/ 与 lock 文件。完整的默认忽略清单在官方参考页 cursor.com/docs/reference/ignore-file，那一页不在我们整理的落盘范围内，具体条目请以官方原文为准。

.cursorignore 这个文件本身也在受保护之列。cursor.com/docs/agent/security/run-modes 的沙箱默认行为表里写明，Cursor 会保护 .git/config、.git/hooks、.vscode、.cursorignore 这类路径；同一张表的 Workspace files 那行写的是沙箱内对工作区文件可读可写，而”.cursorignore can hide files from the agent”。换句话说，沙箱和忽略规则是两层不同的东西，同时生效。

怎么确认是这个问题

按顺序做这几个动作，每一步都能把范围切掉一块。

确认文件位置。官方文档写明 .cursorignore 建在项目根目录（project root）。不在根目录，规则就不在文档描述的生效路径上。
确认不是 .gitignore 的效果。Agent 找不到文件时，troubleshooting 页给的排查顺序是先看 .cursorignore，第二步就是看 .gitignore——“Patterns there can also prevent Agent from discovering files”。
用 @ 提及做一次判定。文档写明被忽略的文件会被挡在 @ 提及之外。如果你能用 @ 把这个文件正常带进对话，说明它压根没被规则命中，问题在 pattern 而不在”不生效”。
看内容是从哪条通道进来的。如果敏感内容是跟着一段终端命令的输出、或者某个 MCP 工具的返回值出现的，那就不是规则失效——帮助页明确写了这两条通道跑在 Cursor 的文件访问控制之外。
如果你是通过 SDK 起的本地 agent，先怀疑缓存。cursor.com/docs/sdk/typescript 里有个 local.workspaceScanCacheTtlMs，控制 SDK 复用一次 workspace scan（rules、skills、AGENTS.md、ignore files）的时长，文档写明默认二十秒、并说明”a rule added after the process started can go unseen for this long”，环境变量 CURSOR_RIPWALK_CACHE_TTL_MS 设同一个值。这是文档写明的默认值，随版本可能变动。同族的 platform.prewarmLocalWorkspace(options) 也是提前解析 rules、skills、MCP servers 和 ignore files。长驻宿主进程里刚加的忽略规则一时不生效，先排掉这一条。

处置：按文档语义分层

第一层，把规则写对。 官方帮助页给的示例就是这几行：

node_modules/
dist/
*.min.js
.env*

第二层，承认它挡不住终端与 MCP，改用确定性手段。 Cursor 的 hooks 里有 beforeReadFile，文档描述是”Called before Agent reads a file. Use for access control to block sensitive files from being sent to the model”，输入含 file_path、content、attachments，输出是 permission 取 allow 或 deny，外加可选的 user_message。这里有个默认值必须知道：文档写明 beforeReadFile 的 hook 失败（crash、timeout、无效 JSON）默认会被记录下来并放行这次读取，要改成失败即拦，得在 hook 定义上写 failClosed: true。

{
  "version": 1,
  "hooks": {
    "beforeReadFile": [
      { "command": ".cursor/hooks/guard-read.sh", "failClosed": true }
    ]
  }
}

项目级配置放在 <project-root>/.cursor/hooks.json，用户级放 ~/.cursor/hooks.json；文档还提醒项目 hooks 是从项目根目录执行的，脚本路径要写成 .cursor/hooks/xxx.sh 这种形式，别写 ./hooks/xxx.sh。

第三层，终端侧用沙箱兜。 Cursor CLI 的参数表里有一条与忽略语义相近的：

agent sandbox run --blocked-patterns <patterns>

文档对它的描述是”Comma-separated list of gitignore-style patterns to block”。注意这是 CLI 沙箱的阻断参数，与项目里的 .cursorignore 是两套东西；我们在落盘的 CLI 文档里没有找到 CLI 侧关于 .cursorignore 的对应说明。以上为按官方文档中的参数语义组合的示例，未经实测，以官方文档与 --help 的实际输出为准。

Windows 侧要额外注意一点。 沙箱这一层，官方文档只写了 macOS（Seatbelt / sandbox-exec，要求 Cursor v2.0 或更高）与 Linux（Landlock + seccomp，要求内核 6.2 或更高并启用 unprivileged user namespaces，不满足时回退为逐条询问审批）的实现，我们没有找到 Windows 侧沙箱的对应说明。所以在 Windows 上，别把”沙箱会兜住”当成前提，重心放在审批、hooks 和文件系统权限上。hooks 的系统级分发路径文档倒是给全了：Windows 是 C:\ProgramData\Cursor\hooks.json，macOS 是 /Library/Application Support/Cursor/hooks.json，Linux/WSL 是 /etc/cursor/hooks.json。

Cloud Agent 侧同理。 cursor.com/docs/cloud-agent/security 把”File exclusion（把敏感路径加进 .cursorignore）“列为控制提示注入风险的层之一，但它是和网络出口控制、Runtime Secrets 脱敏、草稿 PR 人工把关并列的一层，不是单独顶用的一层。

处置后怎么验证

用 @ 再提一次那个文件，看它还能不能被带进对话——这是文档写明会被忽略规则挡住的入口。
改完忽略规则后重新索引：troubleshooting 页写明的做法是打开命令面板搜索 “Reindex”。
上了 beforeReadFile 的话，被拒绝时可以靠 user_message 确认 hook 真的跑到了。
云端场景有个前提要记住：文档写明 cloud agents 会跑仓库里 .cursor/hooks.json 的 command 类 hooks，beforeReadFile 在支持列表里；但云端 agent 早期的探索性回合可能处在只读环境，那些回合 hooks 不运行，要等到环境可写才开始。别拿最开头几轮的表现当验证结果。

什么情况说明不是这个原因

内容是从终端输出或 MCP 工具返回里进来的。 帮助页把这两条通道明确写在了作用范围之外，所以这不是规则失效，改 pattern 的写法也不解决问题，只能靠审批、沙箱或 hooks。
Agent 说找不到文件，但那个文件被 .gitignore 命中了。 troubleshooting 页把 .gitignore 单列为一条独立成因，文档也只说 .cursorignore 是 .gitignore 之外的额外排除，没有写明它能反向解除 .gitignore 的效果——这个方向先去官方 ignore 参考页确认，别在 .cursorignore 里反复试。
文件根本没进过仓库，或者路径不在工作区里。 这类先确认工作区范围，跟忽略规则无关。
Agent 功能整体起不来。 比如 troubleshooting 页写的 “Agent Execution Timed Out”，文档说的成因是扩展宿主没在规定时间内完成启动，排查方向是导出日志，跟忽略规则不沾边。
Tab 补全相关的现象。 hooks 里 Tab 是独立的一套表面（beforeTabFileRead / afterTabFileEdit），文档把它和 Agent hooks 明确分开；至于 .cursorignore 与 Tab 补全之间是什么关系，官方文档没有说明这一点，别按 Agent 的结论去推。

最后重复企业页那句话，它比任何排查步骤都重要：.cursorignore 不是安全边界。真要拦住的东西，用文件系统权限、加密，或者 failClosed 的 hook，别指望一行 pattern。

本文依据 Cursor 官方文档（cursor.com/docs 与 cursor.com/help）于 2026-08-18 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的设置项与命令随版本变动，请以官方文档最新内容为准。本文不涉及订阅价格、额度与模型清单，相关信息请以官方定价与模型说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。