Cursor @Codebase、@Docs、@Files 到底用哪个？实战场景决策指南

Cursor 的 @ 符号系统看着简单：@Codebase、@Files、@Docs，点一下就能给 AI 加上下文。但实际用起来，很多人会卡在一个问题上——明明知道要找什么代码，却不知道该用哪个符号。

选错了，AI 要么塞进来一大堆无关内容，要么找不到你真正需要的那个文件。时间长了，对话历史里全是重复查询，Token 用了一堆，问题还没解决清楚。

这篇文章不讲功能定义，只讲一件事：具体场景下，如何快速判断该用哪个 @ 符号。看完后你会有一个清晰的决策思路，不用每次都纠结。

一、@符号系统核心对比：6 个功能一目了然

先说一个关键结论：根据 BetterLink Blog 的实战统计，80% 的开发时间应该用 @Codebase，而不是手动挑文件。这个数字听起来夸张，但背后的逻辑很简单——@Codebase 的核心优势不是搜索，而是让 AI 帮你发现你可能忽略的关联代码。

下面这 6 个符号，按使用频率从高到低排列：

@Codebase（60-80%）：全库语义搜索。你问一个问题，AI 自动在代码库里找最相关的文件、函数、类型定义。不用知道文件在哪，不用手动选择。适用场景包括：项目架构理解、代码重构、跨文件问题定位。Token 消耗比较高，因为索引覆盖整个代码库。

@Docs（10-15%）：引用外部文档。可以直接调用内置的框架文档（React、Vue、Astro），也可以通过 URL 添加自定义文档源。适用场景：使用新发布的库、查阅最新 API 规范、接入团队知识库。

@Files（5-10%）：精确引用某个文件的完整内容。当你明确知道文件名，或者需要修改配置文件（如 vite.config.ts）时用这个。文件超过 600 行的话，@Files 比 @Codebase 更精准。代价是 Token 消耗较高，因为完整文件内容都会进上下文。

@Code（5-10%）：引用精确的代码片段。只塞进你选中的那段代码，不带整个文件。适用场景：局部代码优化、调试一小段逻辑、避免文件级上下文污染。Token 消耗最低。

@Folders（5%以下）：引用整个目录的结构和内容概览。适用场景：模块重构、生成新组件、检查架构一致性。Token 消耗高，涉及多个文件。

@Repo（特定场景）：Repository context。适用场景：多仓库项目、需要分析版本历史、跨 repo 的问题定位。Token 消耗中等。

这 6 个符号不是互斥的，可以在同一次对话里组合使用。比如先 @Codebase 获取全局信息，再用 @Files 锁定关键文件，最后用 @Docs 补充官方文档说明。关键是：根据问题类型选择，而不是盲目堆叠。

二、决策树：问题类型 → @符号选择

选符号的核心逻辑只有一个问题：你知道代码在哪吗？

不知道的话，用 @Codebase。知道的话，用 @Files 或 @Code。如果还缺文档说明，就加 @Docs。

具体展开来说：

场景 1：不知道文件位置
比如你在重构一个 Next.js 项目，突然想修改某个 API 的返回格式，但不确定类型定义在哪个文件里——可能在 types/，也可能在 components/，甚至可能在某个 utils.ts 里顺手定义的。

这时候用 @Codebase。直接在 Chat 里写：“帮我找到 ApiResponse 类型的定义，并修改返回格式。” AI 会自动扫描整个代码库，找到所有引用这个类型的地方，包括你可能忽略的那个 utils.ts。

场景 2：明确知道文件名
比如你要修改 vite.config.ts 的代理配置，或者重构 src/utils/auth.ts 的某个函数。文件路径清楚，内容也比较长（超过 600 行）。

用 @Files。点一下 @Files，选择目标文件，AI 就会拿到完整内容。这样比 @Codebase 更精准，避免 AI 返回一堆”相关但无关紧要”的文件。

场景 3：需要查阅最新文档
比如你用了一个刚发布的库（上周才上线），或者查某个框架的最新 API 用法（训练数据可能没覆盖）。

用 @Docs。输入 @Docs，选择内置框架文档，或者粘贴 URL 添加新文档源。关键是：要在 prompt 里强调”使用文档中的最新用法”，否则 AI 可能会用它记忆里的旧版本 API。

场景 4：只关注某个代码片段
比如你在调试一个函数的逻辑，只需要优化那几行代码，不想把整个文件塞进上下文。

用 @Code。选中那段代码，按 Cmd+K 触发内联编辑，或者在 Chat 里用 @Code 引用。Token 消耗最低，上下文最干净。

场景 5：模块重构或生成新组件
比如你要重构整个 components/ 目录，或者生成一个新的 features/ 模块，需要保证架构一致性。

用 @Folders。它会拿到目录结构概览和关键文件内容，AI 能理解整个模块的组织方式，生成符合现有风格的代码。

场景 6：多仓库或版本历史分析
比如你的项目依赖多个 Git 仓库，或者需要分析某次 commit 的影响范围。

用 @Repo。它会提供 Repository context，包括版本历史、跨仓库的依赖关系。

---

简单来说，决策树的核心就是一句话：不确定位置用 @Codebase，确定位置用 @Files/@Code，缺文档用 @Docs。剩下两个符号（@Folders、@Repo）是特定场景的补充。

三、@Codebase vs @Files：核心差异与实战案例

这两个符号是最容易混淆的，差异点只有一个：AI 帮你找，还是你自己指。

@Codebase 的价值不是”搜索”，而是”发现”。你问一个问题，AI 会在整个代码库里做语义匹配，返回最相关的文件、函数、类型定义。关键在于：它可能会返回你没想到的文件。比如你问”如何修改 API 返回格式”，AI 可能会返回：

• API handler 文件（你预期的）
• 类型定义文件（你可能知道的）
• 某个 utils.ts 里顺手定义的类型别名（你可能忽略的）
• 某个测试文件里的 mock 数据（你可能完全没注意）

这就是 @Codebase 的核心优势：AI 会发现你可能忽略的关联代码。

@Files 的价值是”精准”。你明确指定文件，AI 拿到完整内容，不会有歧义。代价是：你得知道文件在哪，而且要承受更高的 Token 消耗（完整文件内容都会进上下文）。

---

实战案例 1：API 返回格式修改（@Codebase 更适合）

场景：你有一个 Next.js API，返回格式如下：

// src/app/api/users/route.ts
export async function GET(request: Request) {
  const users = await db.query('SELECT * FROM users');
  return Response.json({ data: users, total: users.length });
}

你想把返回格式改成 { users, count }，但不确定类型定义在哪。

如果用 @Files，你得手动找所有相关文件：route.ts、某个可能的 types.ts、前端调用这个 API 的组件。这个过程容易漏掉文件。

用 @Codebase，直接在 Chat 里写：

@Codebase
帮我修改用户 API 的返回格式，从 { data, total } 改成 { users, count }。
需要同步修改所有相关的类型定义和前端调用代码。

AI 会返回：

找到以下相关文件：
1. src/app/api/users/route.ts - API handler
2. src/types/api.ts - ApiResponse 类型定义
3. src/components/UserList.tsx - 前端组件（调用该 API）
4. src/utils/mock.ts - 测试 mock 数据（也用了这个格式）

你一眼就能看到 mock.ts 也用了这个格式——这个文件你之前根本没注意。

实战案例 2：vite.config.ts 配置优化（@Files 更适合）

场景：你想修改 Vite 的代理配置，文件路径清楚：vite.config.ts。

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': 'http://localhost:3000'
    }
  }
})

目标是把代理改成支持多环境（开发、测试、生产）。

这种情况下，用 @Files 更合适。原因：

1. 文件位置明确
2. 内容不长（通常 50-200 行）
3. 不需要跨文件查找

在 Chat 里写：

@Files vite.config.ts
帮我修改代理配置，支持多环境（开发、测试、生产）。
环境配置从 .env.development、.env.test、.env.production 读取。

AI 会拿到完整的 vite.config.ts，直接给你修改方案：

// vite.config.ts
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');
  return {
    server: {
      proxy: {
        '/api': env.API_URL || 'http://localhost:3000'
      }
    }
  }
})

---

总结：不知道位置，或者需要发现隐藏关联，用 @Codebase；知道位置，或者文件很长需要完整理解，用 @Files。

四、@Docs：新库使用与文档集成

@Docs 解决的问题是：AI 的训练数据跟不上文档更新。

比如你用了一个上周才发布的库，或者某个框架刚改了 API 用法（React 19 的新 hooks、Next.js 15 的 Turbopack）。AI 的训练数据可能停留在几个月前，生成代码时会用旧版本 API。

@Docs 的原理：它会实时检索你指定的文档，解析内容，塞进上下文。AI 在生成代码时，会优先参考文档里的最新规范。

---

使用方式

操作很简单：

1. 在 Chat 里输入 @Docs
2. 选择内置框架文档（React、Vue、Astro、Tailwind、Next.js 等）
3. 或者粘贴 URL，添加自定义文档源

自定义文档源很实用。比如你的团队有一个内部知识库（飞书文档、GitHub Wiki），你可以把 URL 加进去，AI 就能参考团队规范生成代码。

---

实战案例：React 19 新 hooks

假设你要用 React 19 的 useOptimistic hook，但不确定最新用法。

直接在 Chat 里写：

@Docs React
帮我实现一个 optimistic update 功能，用 React 19 的 useOptimistic hook。
场景：点赞按钮，点击后立即显示 +1，等待服务器确认。

AI 会先检索 React 官方文档，拿到最新的 useOptimistic API 说明，然后生成符合规范的代码：

import { useOptimistic } from 'react';

function LikeButton({ initialLikes, onSubmit }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state, newLike) => state + newLike
  );

  async function handleClick() {
    addOptimisticLike(1); // 立即显示 +1
    await onSubmit();     // 等待服务器确认
  }

  return <button onClick={handleClick}>{optimisticLikes} Likes</button>;
}

---

注意事项：训练数据可能覆盖 @Docs

有个坑需要注意：AI 可能同时参考训练数据和 @Docs。如果训练数据里的旧用法”印象更深”，AI 可能会混合新旧 API，生成奇怪的代码。

解决办法：在 prompt 里强调”使用文档中的最新用法”。

比如：

@Docs React
请使用文档中的最新用法（React 19），不要用训练数据里的旧 API。

这样 AI 会优先参考 @Docs 内容，降低旧版本的影响。

---

什么时候该用 @Docs？

简单判断：如果库/框架发布时间晚于 AI 训练截止日期，或者 API 有重大更新，就用 @Docs。

比如：

• React 19（2024 年底发布，重大 API 更新）
• Next.js 15（2024 年底，Turbopack 默认启用）
• Supabase 最新功能（实时更新的文档）
• 团队内部规范（AI 训练数据不可能有）

如果库比较稳定（React 18、Vue 3、Tailwind 3），训练数据覆盖良好，@Docs 的必要性就不高。

五、上下文管理最佳实践

用好 @符号只是第一步，第二步是管好上下文。很多人踩过这个坑：对话历史越长，AI 理解越跑偏，最后生成的代码完全偏离初衷。

核心原则：对话要短，功能要分

完成一个功能后，重启对话。不要把”重构 API”、“修复 Bug”、“添加新功能”混在同一个对话里。

为什么？因为每个功能需要的上下文不一样。重构 API 时，AI 需要的是类型定义、API handler、前端调用代码；修复 Bug 时，AI 需要的是错误日志、相关代码片段、测试用例。混在一起，上下文会越来越杂，AI 的理解会越来越模糊。

简单操作：在 Chat 面板右上角点击 “Clear Chat”，或者按快捷键重开一个对话。

---

小编辑 vs 复杂任务

两种场景用不同的方式：

小编辑（改一行代码、调一个参数）：用内联编辑（Cmd+K）。选中目标代码，按 Cmd+K，输入修改指令。当前文件和选中内容自动作为上下文，不需要额外设置。

复杂任务（重构模块、生成新组件）：用 Chat + @-mentions。先 @Codebase 获取全局信息，再 @Files 锁定关键文件，最后写清楚任务描述。这样上下文更完整，AI 的理解更准确。

---

索引优化：用 .cursorignore 排除干扰文件

@Codebase 的索引是全库覆盖，但不是所有文件都需要 AI 看到。

比如：

• node_modules/（依赖库，AI 不需要）
• dist/、build/（编译产物）
• .env、.env.local（敏感配置）
• 大型静态资源（图片、视频）

用 .cursorignore 文件排除这些目录。和 .gitignore 分开维护，原则是：AI 需不需要看到这个文件？

# .cursorignore
node_modules/
dist/
build/
.env
.env.local
*.log
*.png
*.jpg

这样 @Codebase 的索引范围更精准，查询速度更快（5-10 秒降到 2-3 秒），返回结果也更相关。

---

定期更新 README.md

一个容易被忽略的习惯：在 README.md 里记录项目状态和结构。

为什么？因为 README.md 是 @Codebase 索引的关键文件之一。AI 在理解项目架构时，会优先参考 README。如果你的 README 写清楚了：

• 项目结构（目录说明）
• 核心模块（哪些文件负责什么功能）
• 最近改动（新功能、重构计划）

AI 在处理复杂任务时，能更快理解全局，减少重复查询。

---

Pro 用户的优势：更广的索引范围

Cursor Pro 用户可以索引整个代码库的语义，Free 用户有索引范围限制。如果你的项目超过 500 个文件，Pro 版本的 @Codebase 效果会明显更好。

但这不代表 Free 用户就没法用。关键还是：管好上下文，用对符号，排除干扰文件。Pro 只是锦上添花，不是雪中送炭。

六、常见问题与解决方案 FAQ

问题 1：@Codebase 返回的结果和代码库不一致

症状：你刚改了某个文件，但 @Codebase 返回的还是旧内容。或者某个明明存在的文件，@Codebase 找不到。

原因：索引没有同步更新。

解决办法：

1. Cursor Settings → “Reindex Codebase”（强制重新索引）
2. 或者移除项目文件夹，重新添加（更彻底）

这个操作需要等 1-2 分钟，索引完成后问题会消失。

---

问题 2：@Codebase 返回错误匹配

症状：你问”如何修改 UserService”，AI 返回的是 utils/user.ts，而不是你预期的 services/UserService.ts。

原因：语义匹配有歧义，AI 可能误判了相关性。

解决办法：

1. 用 @Files 明确指定正确文件
2. 或在 prompt 里说明文件路径：“修改 src/services/UserService.ts”

@Codebase 的优势是自动发现，但代价是有误差。精准任务还是用 @Files。

---

问题 3：AI 用了旧版本 API，明明加了 @Docs

症状：你加了 @Docs React，但 AI 生成的代码还是 React 18 的写法。

原因：训练数据的”印象”太深，覆盖了 @Docs 内容。

解决办法：在 prompt 里强调：

@Docs React
请使用文档中的最新用法（React 19），不要用训练数据里的旧 API。

加这句话后，AI 会优先参考 @Docs。

---

问题 4：@Codebase 查询太慢（5-10 秒）

症状：每次用 @Codebase，都要等很久。

原因：索引范围太大（包含 node_modules、dist 等）。

解决办法：检查 .cursorignore 配置，排除不必要的文件：

# .cursorignore
node_modules/
dist/
build/
*.log
*.png

排除后，索引范围缩小，查询速度会降到 2-3 秒。

---

问题 5：对话历史太长，AI 理解跑偏

症状：对话里已经讨论了三四个功能，AI 的回复越来越偏离你的初衷。

原因：上下文污染——每个功能的上下文混在一起。

解决办法：重启对话。在 Chat 面板右上角点击 “Clear Chat”，开一个新的对话。每个功能单独处理，上下文更干净。

---

问题 6：Token 消耗太高，超出预算

症状：每次对话都用掉大量 Token，Pro 额度很快就没了。

原因：符号选择不当，塞进了太多无关内容。

解决办法：

1. 小编辑用 Cmd+K（内联编辑），不触发 @-mentions
2. 精准任务用 @Files/@Code，避免 @Codebase 返回一堆”相关但无关”的文件
3. 用 .cursorignore 排除大型文件（node_modules、dist）

Token 消耗的核心原则：精准引用，避免全库搜索。

总结

Cursor 的 @符号系统，核心逻辑就一句话：不确定位置用 @Codebase，确定位置用 @Files/@Code，缺文档用 @Docs。

80% 的开发时间应该用 @Codebase。这不是夸张，而是因为 @Codebase 的真正价值在于”发现”——AI 会找到你可能忽略的关联代码，比如那个随手定义在 utils.ts 里的类型别名，或者某个测试文件里的 mock 数据。

但 @Codebase 不是万能的。文件超过 600 行，或者你明确知道位置，用 @Files 更精准。调试一小段代码，用 @Code 最省 Token。新库或者最新 API，加 @Docs 确保规范准确。

上下文管理同样重要。对话要短，功能要分。完成一个任务后重启对话，不要让历史越长越杂。用 .cursorignore 排除干扰文件，定期更新 README.md，AI 的理解会更准确。

下次开发时，先问自己：我是知道文件位置，还是需要 AI 查找相关代码？如果不确定，先用 @Codebase——AI 会帮你发现隐藏的关联。如果确定，就精准引用，避免上下文污染。

用好这套符号，Cursor 才能真正成为你的编程搭档，而不是一个只会返回大堆内容的搜索工具。