Cursor 的 @ 上下文引用全解（@codebase/@web/@docs）
Cursor 的 @ 是给 AI”指路”的符号：你在对话框里打一个 @，就能把指定的代码文件、整个代码库、一段官方文档、甚至实时网页塞进这次提问的上下文，让 AI 不再瞎猜、而是基于你真实的项目来回答。
很多人用 Cursor 觉得”它怎么老答错、老改错文件”，根因往往不是模型笨，而是你没把对的上下文喂给它。这篇把 Cursor 的几个核心 @ 引用——@codebase、@web、@docs、@file、@folder、@git、@terminal——逐个讲清各自管什么、什么场景用哪个，让你的每次提问都”喂得准”。
@ 引用是什么，和”直接打字描述”有什么不一样
直接在对话框里用自然语言描述需求，AI 只能靠它”看得见”的那点上下文（当前打开的文件、最近改动）连蒙带猜。@ 引用是把上下文从”猜”变成”指定”：你明确告诉它”看这个文件""查这份文档""搜一下实时网页”,信息密度和准确度立刻上一个台阶。
一句话区分：没把握时多打一个 @，比反复纠正 AI 省时间得多。 下面分门别类拆。
@codebase：让 AI 理解你的整个项目
@codebase 是把整个代码库作为检索范围。Cursor 会对项目做语义索引，当你问”用户登录的逻辑在哪""这个项目用了什么状态管理”，它会自动检索相关文件再回答，而不是只看你当前打开的那一个。
什么时候用：
- 刚接手一个陌生项目，问”整体架构是怎样的""支付流程涉及哪些模块”
- 跨文件的改动，比如”把所有用到旧 API 的地方都换成新的”
- 你自己也不确定相关代码在哪个文件，需要 AI 帮你”全库找一下”
注意：@codebase 检索的前提是项目已经建好索引，大型仓库首次索引需要时间；索引设置与忽略规则以官方文档为准。它擅长”找相关”,但不等于把全库每一行都塞进上下文——对精确的小改动，反而该用更窄的 @file。
举个真实场景对比：接手一个陌生的电商项目，你想改”下单后自动扣库存”的逻辑。直接问”帮我改一下扣库存的代码”，AI 大概率抓的是它当前打开的那个文件，改错地方的概率很高。换成 @codebase 项目里下单成功之后扣减库存的逻辑在哪几个文件，先列出来，别直接改，它会先给你一份文件清单（可能是 order.service.ts、inventory.repository.ts、一个消息队列消费者），你确认范围没错，再让它改。先问清楚”在哪”，再动手改”怎么改”，这一步能省掉后面大半的返工。
另外要提醒一句：@codebase 检索出来的相关代码越多，喂进模型的 token 越多，响应速度会变慢，回答也可能因为信息过载而抓不住重点。一次任务真正相关的文件超过五六个的时候，不如手动 @file 精确指定，比全交给检索更省心。
@file 与 @folder：精准锁定文件和目录
当你已经知道要改哪个文件，就别让 AI 全库乱找，直接 @file 点名。
@file：引用单个文件的完整内容。最常用——“参照@utils.ts的写法，给@api.ts也加上错误处理”。@folder：引用整个目录。适合”这个@components/目录下的组件风格统一一下”这类范围明确的批量任务。
判断口诀：知道具体文件 → @file；知道大致范围、想批量处理一个目录 → @folder；完全不知道在哪 → 才用 @codebase 让它帮你找。喂得越窄越准，AI 越不容易跑偏改错文件。
@file 可以叠加多个，这一点很多人不知道。比如让 AI 照抄某个文件的错误处理风格，别只 @ 目标文件，把”参照对象”也一起喂进去：@file:utils.ts @file:api.ts 参照 utils.ts 里 fetchWithRetry 的重试和错误处理写法，给 api.ts 里的三个请求函数也加上。两个文件同时在上下文里，AI 才能真正”照着抄”，而不是凭记忆猜一个通用写法出来。只喂目标文件、不喂参照文件，是最常见的翻车原因之一。
@web：让 AI 联网查实时信息
模型有知识截止时间，问它”最新版本怎么配""这个新报错网上怎么解”，它可能用过时信息瞎答。@web 让 Cursor 实时联网搜索，基于当前网页内容回答。
什么时候用：
- 查某个库的最新用法/新版破坏性变更
- 排查一个较新的报错，想让它综合网上的解法
- 需要时效性信息，而不是模型脑子里的旧知识
@web 解决的是”模型不知道新东西”的问题。它和 @codebase 正好互补：一个往外查公网，一个往内查你的项目。
但有一点得说清楚：@web 查回来的内容质量取决于搜到的网页质量，遇到过时的博客、版本对不上的教程，AI 照样可能把错的答案讲得很自信。拿到 @web 的回答后，最好追问一句”这个方案是哪个版本适用的，官方文档链接是哪个”，让它把信源亮出来，你自己再判断一遍，别当成绝对正确的答案直接照抄进代码。
@docs：把官方文档喂给 AI
@docs 是引用文档作为上下文。你可以让 AI 基于某个框架/库的官方文档来回答，而不是靠它记忆里可能记串了的 API。Cursor 支持引用内置收录的文档，也支持添加自定义文档源（具体添加方式与支持范围以官方文档为准）。
@web 和 @docs 怎么选：
| 你的需求 | 用哪个 | 原因 |
|---|---|---|
| 查某框架的标准 API 用法 | @docs | 官方文档权威、结构化，答得准 |
| 查最新动态/某个具体报错 | @web | 文档不一定收录，公网更新更快 |
| 让 AI 按你内部文档/约定写 | @docs（自定义源） | 喂你团队自己的规范 |
简单说：要”标准答案”用 @docs，要”最新情报”用 @web。
@git 与 @terminal：把改动和报错喂进去
这两个是排查问题时的利器。
@git：引用 Git 相关上下文，比如某次提交的 diff、当前改动。典型用法是”@git看一下这次改动，帮我写一段提交说明”或”这次改动有没有引入明显问题”。写提交说明这个场景尤其好用：与其自己回忆”我这次到底改了啥”，不如让 AI 直接读 diff 总结，你再手动调整措辞，比空着脑袋硬想快得多。@terminal：引用终端里的输出内容。跑命令报了一长串错，与其手动复制粘贴，不如@terminal让它直接读终端，“这个报错怎么解”。
排查类问题的标准组合：@terminal（把报错喂进去）+ @file（指出相关代码文件）+ 必要时 @web（查公网解法），三件套喂齐，命中率远高于干巴巴一句”我报错了”。
举个具体例子：跑 npm run build 报了一堆 TypeScript 类型错误，标准操作是——第一步 @terminal 把报错原文喂进去；第二步根据报错里提到的文件名，把对应的一两个文件 @file 进来；第三步如果报错信息里提到某个第三方库的类型定义有变化，再补一个 @web 查一下这个库最近是不是升级了破坏性版本。三步做完再问”这个类型错误怎么修，给出改动”，AI 给出的方案会比你光贴一段报错文字准确得多，因为它同时看到了”报了什么错""错在哪段代码""外部原因是不是版本变了”。
新手常见坑（4 条）
- 什么都用
@codebase：全库检索慢且容易引入无关上下文。已知文件就用@file，越精准越好。 - 该联网却不联网：问最新版本/新报错时忘了
@web，AI 拿旧知识硬答还很自信，反被误导。 - 报错靠手敲转述：把终端报错用大白话复述给 AI，丢了关键堆栈信息。直接
@terminal喂原文。 - 一次塞太多
@：把七八个文件全@进来，上下文反而被稀释、抓不住重点。只喂”这次任务真正相关”的那几个。 - 只喂目标文件、忘了喂参照文件：想让 AI”照着某个写法改”,却只
@了要改的文件，没把参照对象一起喂进去，AI 只能凭记忆猜一个通用写法，结果和你想要的风格对不上。
把这套引用习惯养成后，建议再配一套项目规则文件，让 AI 默认就懂你的项目约定——可参考 Cursor Rules 最佳实践（规划中）。想系统从零上手 Cursor，看 Cursor 使用教程（规划中）。
常见问题
Cursor 里 @ 符号到底怎么用？
在对话框（Chat 或行内编辑）输入 @，会弹出候选菜单，可选 @file、@folder、@codebase、@web、@docs、@git、@terminal 等。选中后它就作为本次提问的上下文。各引用的具体可用范围以官方文档为准。
@codebase 和 @file 有什么区别，该用哪个？
@codebase 是让 AI 在整个项目里检索相关代码，适合你不知道代码在哪、或要做跨文件的全局改动；@file 是点名某个具体文件。知道改哪个文件就用 @file，更准更快；不知道在哪才用 @codebase。
@web 和 @docs 都是查资料，区别在哪？
@web 实时联网搜公网，适合查最新动态、新报错；@docs 引用官方/自定义文档，适合查标准 API 用法。要”最新情报”用 @web，要”标准答案”用 @docs。
为什么加了 @ 上下文，AI 还是答错？
通常是喂的上下文不对或太杂：要么没喂到真正相关的文件，要么一次塞太多无关内容把重点稀释了。先收窄到这次任务最相关的 1-3 个文件/文档，报错类问题务必把 @terminal 原文喂上，准确率会明显提升。
👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。