Cursor 怎么把文件加入 AI 上下文？引用目标文件并排除敏感内容

让 Cursor 理解代码任务，不需要把整个项目一次性“喂给 AI”。你已经知道入口时，用 @ 引用具体文件或目录；范围不确定时，先描述任务，让 Agent 搜索并解释它找到的文件。真正需要同时解决的是两件事：给足完成任务所需的上下文，以及把密钥、客户数据和无关大目录挡在范围之外。

先判断该引用文件，还是让 Agent 搜索

Cursor 官方提示词文档说明，在聊天输入框键入 @ 后可以选择文件、目录、终端输出、聊天、Git diff 或浏览器上下文。已知文件时，精确引用能减少歧义；不知道实现位于哪里时，不必随意附上大目录，Agent 可以先搜索代码库。

• 适合 @文件：修一个明确组件、解释一段配置、为指定函数补测试。
• 适合 @目录：任务涉及一个边界清楚的小模块；选择目录后还可以继续向下进入子目录。
• 适合先搜索：只知道页面行为、错误文本或接口现象，不知道源文件。
• 适合 @Git diff：要审查当前工作区或分支的变化，而不是重读整个仓库。

准备最小且安全的上下文

先列出任务真正需要的入口、类型、测试和配置模板，检查文件中没有真实凭证或客户数据。

例如修复登录表单校验，通常需要表单组件、校验规则、请求类型和相关测试；真实 .env、生产日志、用户导出数据和构建产物不应加入。配置示例可以引用脱敏的 .env.example，不要用真实凭证说明字段。

用 .cursorignore 排除不该访问的内容

在仓库根目录创建 .cursorignore，语法与 .gitignore 类似。官方文档说明，被列出的文件会从 Agent、Tab、Inline Edit 和 @ 引用访问中排除。下面是一个可按项目调整的起点：

# 本地秘密与证书
**/.env
**/.env.*
**/secrets.json
**/credentials.json
**/*.pem
**/*.key

# 客户导出与日志
private-data/
exports/
**/logs/
*.log

# 大型生成物
dist/
coverage/
.cache/

不要机械复制规则后就结束。项目若需要 Agent 阅读 .env.example，应确认通配模式没有误伤；父目录已整体排除时，嵌套文件的重新包含规则可能不会生效。官方文档也提供全局忽略设置和可选的分层 .cursorignore，但入口以当前版本设置页为准。

引用文件并发出可执行请求

1. 在提示框用 @文件 或 @目录 加入目标范围，目录过大时继续向下选择子目录。
2. 附上可观察的问题、预期行为和仓库真实命令，不要只写“学习这些文件”。
3. 要求 Agent 先返回它准备使用的文件清单，以及每个文件与任务的关系。
4. 发现缺失时只补必要的类型、测试或调用方；发现无关文件时从上下文移除。
5. 确认范围后再允许修改，并在完成后按清单逐项查看 diff。

下面这段可直接替换文件名使用：

@src/features/login/LoginForm.tsx
@src/features/login/validation.ts
@src/features/login/LoginForm.test.tsx

任务：空邮箱提交时应显示现有中文校验提示，合法邮箱的提交行为不变。
请先只读这些文件并回答：
1. 校验入口和现有测试模式在哪里；
2. 是否还缺少完成任务必需的文件；
3. 计划修改哪些文件，为什么。
不要读取或输出任何 .env、凭证、生产日志和客户数据。
我确认范围后再修改，并运行项目现有的相关测试。

验证引用与排除都生效

通过标准是任务所需文件可被引用、敏感测试文件被阻止、回答能给出具体文件依据。

1. 创建一个不含真实秘密的测试文件，例如 private-data/ignore-check.txt，内容只写随机标记。
2. 尝试在 @ 选择器中引用它，并请 Agent 读取该标记；预期是文件不可通过受保护的代码上下文访问。
3. 再引用一个允许访问的测试文件；预期是 Agent 能准确说出路径和相关代码，而不是泛泛回答。
4. 查看 Agent 给出的依据。它若引用了不存在的函数或路径，先让它重新搜索，不要继续改代码。

需要特别区分：官方文档明确说明，.cursorignore 无法阻止 Agent 使用终端和 MCP 工具访问同一文件。因此，忽略规则只是一层上下文控制。真实秘密仍要依靠操作系统权限、秘密管理、仓库清理，以及对终端和第三方工具调用的审批。

常见失败及处理

• @列表找不到文件：检查文件是否被 .gitignore、默认忽略规则或 .cursorignore 排除，再核对打开的仓库根目录。
• 目录引用后回答变差：撤下大目录，改为入口、类型、直接调用方和测试四类文件；新开会话时只带当前任务所需信息。
• 忽略规则误伤：从最具体的规则开始验证。不要一开始排除整个父目录后再尝试逐层放行深层文件。
• Agent 仍声称看到了敏感内容：停止任务并检查内容是否来自旧聊天、终端输出、Git diff 或其他工具，不要把“无法 @ 引用”等同于绝对隔离。

适用边界

.cursorignore 能降低访问风险但不是绝对隔离；系统权限、仓库清理和密钥管理仍然必需。

相关问答

@目录越大，回答就越完整吗？

通常不是。无关文件会占用固定上下文窗口并稀释任务重点。已知范围时引用少量关键文件；未知范围时让 Agent 先搜索并给出理由，往往更容易审查。

.gitignore 与 .cursorignore 可以互相替代吗？

用途不同。官方资料说明 Cursor 也会默认忽略 .gitignore 中的文件，但版本控制排除不能替代专门的 AI 访问规则；同时，两者都不是秘密管理系统。

资料与适用范围

本文根据 2026 年 10 月 1 日核验的 Cursor @ 引用与上下文官方文档、.cursorignore 官方文档 整理。示例流程未在你的设备、账号或仓库中实测，界面、方案、权限和项目命令应以当前环境为准。