Cursor @ 符号引用详解
免责声明：本文档是关于 Cursor 官方文档中的 @ 符号引用功能和@文件引用功能的第三方非官方中文翻译和扩展，仅供学习参考。内容可能不完全反映最新的官方信息，请以 Cursor 官方文档 为准。所有商标和版权归 Cursor/Anysphere 公司所有。
本文档详细介绍了 Cursor 中的 @ 符号引用系统，这是一个强大的上下文管理工具，允许您在与 AI 交互时精确地指定引用内容。
@ 符号引用系统概述
在 Cursor 的各种输入框中（如 Chat、Composer 和 ⌘K），您可以通过输入 @ 符号来触发上下文引用功能。这将弹出一个建议菜单，自动显示最相关的上下文选项，帮助您为 AI 提供精确的参考资料。
@ 符号引用是连接您的查询与代码库、文档和其他资源的桥梁，确保 AI 拥有回答问题所需的确切上下文。
键盘快捷操作
- 使用上/下箭头键在建议列表中导航
- 按回车键选择当前高亮的建议
- 如果选择的是类别（如"Files"），菜单会进一步筛选显示该类别中最相关的项目
所有可用的 @ 符号类型
Cursor 提供了丰富的 @ 符号类型，满足不同的上下文需求：
| @ 符号类型 | 描述 | 使用场景 |
|---|---|---|
| @Files | 引用项目中的特定文件 | 当您需要 AI 分析、理解或修改特定文件时 |
| @Folders | 引用整个文件夹 | 提供更广泛的上下文，让 AI 理解项目结构 |
| @Code | 引用代码库中的特定代码片段或符号 | 获取关于特定函数、类或变量的帮助 |
| @Docs | 访问文档和指南 | 引入官方文档或自定义文档作为上下文 |
| @Git | 访问Git历史和变更 | 分析代码变更历史或了解特定提交 |
| @Notepads | 访问记事本内容 | 引用您在Cursor中创建的笔记 |
| @Summarized Composers | 使用已总结的Composer会话 | 引用之前的AI交互结果 |
| @Cursor Rules | 使用Cursor规则 | 引入自定义的AI行为规则 |
| @Web | 引用外部网络资源和文档 | 获取最新信息或外部参考资料 |
| @Link | 创建指向特定代码或文档的链接 | 在回答中提供直接引用 |
| @Recent Changes | 引用最近的变更 | 分析或讨论刚刚进行的代码修改 |
| @Codebase | 引用整个代码库作为上下文（仅限Chat） | 获取关于整个项目的广泛理解 |
| @Lint Errors | 引用Lint错误（仅限Chat） | 修复代码中的语法和风格问题 |
| @Definitions | 查找符号定义（仅限⌘K） | 了解特定符号的定义和用法 |
其他特殊符号
除了@符号外，Cursor还支持其他特殊符号：
- # Files：将文件添加到上下文中而不引用它们
- / Commands：将打开和活动的文件添加到上下文中
@ 符号类型详细说明
下面是每种 @ 符号类型的详细介绍：
@Files - 文件引用
描述：引用项目中的特定文件
使用场景：当您需要 AI 分析、理解或修改特定文件时
使用方法：
- 输入
@后继续输入文件名 - 从建议列表中选择您想要引用的文件
- 文件将被添加到 AI 的上下文中，使 AI 能够访问该文件的内容
示例：
@main.js 这个文件中的路由配置有什么问题？@Folders - 文件夹引用
描述：引用整个文件夹
使用场景：提供更广泛的上下文，让 AI 理解项目结构
使用方法：
- 输入
@后输入文件夹路径 - 从建议列表中选择您想要引用的文件夹
- 文件夹中的所有文件都将被添加到上下文中，但 AI 会根据查询的相关性对它们进行优先级排序
示例：
@src/components/ 这个目录下的组件遵循了什么设计模式？@Code - 代码片段引用
描述：引用代码库中的特定代码片段或符号
使用场景：获取关于特定函数、类或变量的帮助
使用方法：
- 输入
@后开始输入代码元素的名称（如函数名、类名） - 从建议列表中选择匹配的代码元素
- 该代码元素及其上下文将被添加到 AI 的参考中
示例：
@authenticateUser 这个函数的安全性如何？有没有潜在的漏洞？@Docs - 文档引用
描述：访问文档和指南
使用场景：引入官方文档或自定义文档作为上下文
使用方法：
- 输入
@Docs后可以浏览可用的文档 - 选择相关文档或添加新的文档URL
- 文档内容将被作为上下文提供给 AI
示例：
@Docs React 如何使用React的上下文API来管理全局状态？@Git - Git历史引用
描述：访问Git历史和变更
使用场景：分析代码变更历史或了解特定提交
使用方法：
- 输入
@Git后可以浏览仓库的提交历史 - 选择特定的提交或变更
- 该提交的变更信息将被添加到上下文中
示例：
@Git 最近的提交修复了什么问题？这些变更是否合理？@Notepads - 笔记本引用
描述：访问记事本内容
使用场景：引用您在Cursor中创建的笔记
使用方法：
- 输入
@Notepads后选择已保存的笔记 - 笔记内容将被添加到上下文中
- 这对于引用之前记录的想法、计划或临时代码很有用
示例：
@Notepads API设计 请根据我的笔记中记录的API设计原则审查这个接口@Summarized Composers - 已汇总的Composer会话
描述：使用已总结的Composer会话
使用场景：引用之前的AI交互结果
使用方法：
- 输入
@Summarized后选择之前保存的Composer会话 - 该会话的摘要将被添加到当前上下文中
- 可以帮助AI理解之前的讨论和决策
示例：
@Summarized 重构计划 基于之前我们讨论的重构计划，接下来应该优先处理哪部分代码？@Cursor Rules - Cursor规则引用
描述：使用Cursor规则
使用场景：引入自定义的AI行为规则
使用方法：
- 输入
@Cursor Rules后选择已定义的规则 - 这些规则将指导AI如何响应您的查询
- 例如，可以设置代码风格、注释规范或错误处理策略
示例：
@Cursor Rules 代码风格 生成一个新的React组件，遵循我们的代码风格规则@Web - 网络资源引用
描述：引用外部网络资源和文档
使用场景：获取最新信息或外部参考资料
使用方法：
- 输入
@Web后输入搜索查询 - AI将搜索网络并将相关结果作为上下文
- 这对于获取最新技术信息或API文档特别有用
示例：
@Web "React 18 新特性" 如何在我们的项目中利用React 18的新特性？@Link - 链接引用
描述：创建指向特定代码或文档的链接
使用场景：在回答中提供直接引用
使用方法：
- 输入
@Link后粘贴URL或选择要链接的资源 - 该链接将被格式化并添加到上下文中
- AI可以引用这个链接提供的信息
示例：
@Link https://reactjs.org/docs/hooks-reference.html 如何正确使用React Hooks的依赖数组？@Recent Changes - 最近变更引用
描述：引用最近的变更
使用场景：分析或讨论刚刚进行的代码修改
使用方法：
- 输入
@Recent Changes后查看最近的文件修改 - 选择相关的变更
- 这些变更将被添加到上下文中
示例：
@Recent Changes 我刚才的修改可能会导致什么潜在问题？@Codebase - 代码库引用
描述：引用整个代码库作为上下文（仅限Chat）
使用场景：获取关于整个项目的广泛理解
使用方法：
- 输入
@Codebase将整个代码库添加为上下文 - 仅在Chat中可用，因为它可能涉及大量上下文
- AI会尝试理解整个代码库结构和关系
示例：
@Codebase 这个项目的整体架构是什么？有哪些关键模块？@Lint Errors - Lint错误引用
描述：引用Lint错误（仅限Chat）
使用场景：修复代码中的语法和风格问题
使用方法：
- 输入
@Lint Errors查看当前文件或项目中的lint错误 - 选择要解决的错误
- AI将提供修复这些错误的建议
示例：
@Lint Errors 如何一次性修复所有这些lint警告？@Definitions - 符号定义引用
描述：查找符号定义（仅限⌘K）
使用场景：了解特定符号的定义和用法
使用方法：
- 在⌘K命令中输入
@Definitions后输入要查找的符号名称 - 选择匹配的符号
- AI将提供该符号的定义和用法说明
示例：
@Definitions UserContext 这个上下文对象的结构是什么？它在哪些组件中被使用？@Files 引用详解
基本用法
在Chat、⌘K或Composer中，您可以通过以下方式引用文件：
- 输入
@并继续输入文件名或路径 - 从弹出的建议列表中选择所需文件
- 或在
@后直接输入，您将在@Code策略后看到文件搜索结果
为确保引用的文件正确，Cursor会显示文件路径预览。这在有多个同名文件位于不同文件夹的情况下特别有用。
文件预览和分块
当您引用文件时，Cursor会提供文件内容预览，帮助您确认这是否是您想要引用的文件。
长文件处理
在Cursor的Chat中，如果文件内容过长，Cursor会将文件分成更小的块并根据与查询的相关性对它们进行重新排序。这确保了最相关的内容能够优先被处理，同时保持在模型的上下文窗口限制内。
分块处理的优势：
- 优化处理大型文件
- 确保最相关内容优先考虑
- 在不丢失关键信息的情况下适应模型限制
拖放支持
您可以直接从主侧边栏拖放文件到Composer、Chat或⌘K中，将它们作为上下文添加。这提供了一种快速、直观的方式来引用多个文件。
拖放操作步骤：
- 在文件浏览器中找到所需文件
- 点击并按住该文件
- 将其拖动到AI输入框
- 释放鼠标按钮完成添加
高级 @ 引用技巧
组合使用多个 @ 引用
您可以在同一查询中组合使用多个 @ 符号引用，创建复杂而精确的上下文：
@src/api/auth.js @src/components/Login.jsx 这两个文件如何交互？如何改进它们之间的数据流？使用通配符和路径模式
在引用文件或文件夹时，您可以使用通配符和路径模式来匹配多个文件：
@src/utils/*.js 这些工具函数中是否有任何可以合并的重复代码？结合 @Web 和其他上下文
您可以将@Web与特定文件结合使用，获取更全面的答案：
@src/components/DataGrid.jsx @Web "React data grid best practices" 如何优化这个组件的性能？使用 @Docs 引用文档
Cursor预先爬取了一系列第三方文档，可通过@Docs符号访问。您还可以添加自定义文档：
- 使用
@Docs>Add new doc - 粘贴所需文档的URL
- Cursor将索引并学习该文档
- 文档索引完成后，您可以像使用任何其他文档一样将其用作上下文
管理自定义文档
在Cursor设置 > 功能 > 文档中，您可以看到已添加的文档。您可以在此编辑、删除或添加新文档。
其他特殊符号详细说明
# Files - 非引用文件添加
描述：将文件添加到上下文中而不引用它们
使用场景：当您想要提供额外的上下文，但不希望在回答中明确引用这些文件时
使用方法：
- 输入
#后选择文件 - 文件将被添加到上下文，但不会作为明确引用出现在提示中
- 这对于提供背景信息而不分散注意力很有用
示例：
#config.json 我们应该如何重构用户认证逻辑？/ Commands - 活动文件引用
描述：将打开和活动的文件添加到上下文中
使用场景：当您想快速引用当前正在编辑的文件或打开的文件时
使用方法：
- 输入
/查看可用命令 - 选择相关命令来添加活动文件
- 这比手动查找文件要快捷得多
示例：
/active 这段代码中的错误在哪里？使用场景示例
代码理解
@src/components/DataTable.jsx 这个组件的渲染逻辑是什么？性能瓶颈可能在哪里？跨文件关系分析
@models/User.js @controllers/UserController.js 这两个文件之间的数据流是什么样的？是否遵循了MVC模式？代码审查和优化
@src/utils/helpers.js 这个文件中有什么可以优化的地方？有没有潜在的bug或性能问题？学习新项目
@package.json @README.md @main.js 帮我理解这个项目的主要功能和架构批量文件处理
@src/api/*.js 这些API调用是否一致地处理错误？有没有缺少错误处理的地方？常见问题与解决方案
为什么有时找不到文件？
可能原因：
- 文件名或路径输入错误
- 文件位于被忽略的目录中
- 文件尚未保存（新创建的文件）
解决方案：
- 检查文件名和路径拼写
- 确认文件不在
.cursorignore中排除 - 保存新文件后再引用
@ 符号引用与代码库索引的关系
@ 符号引用功能与代码库索引紧密相关。为获得最佳效果：
- 确保您的代码库已正确索引
- 定期更新索引以反映新变更
- 使用精确的引用来减轻对索引的依赖
如何处理大型文件？
当引用非常大的文件时：
- 考虑引用文件的特定部分而不是整个文件
- 使用更精确的查询以帮助AI识别相关内容
- 利用Cursor的自动分块功能来处理大文件
通过精通 @ 符号引用系统，您可以显著提高与 Cursor AI 的交互效率和准确性。这种能力允许您为AI提供精确的上下文，从而获取更相关、更有用的回答，无论是理解复杂代码库还是实现新功能。