@ 引用语法完整指南

沉淀沉淀再沉淀
0 阅读4分钟

@ 引用语法完整指南

@ 是 Claude Code 的上下文注入语法，用于将文件、目录、URL 内容引入对话上下文。

基本语法

@文件路径
@目录路径
@URL

在消息中的任意位置都可以使用，可以混合使用：

> @src/api/user.ts 和 @src/types/user.ts 这两个文件的类型定义一致吗？

引用类型详解

引用单个文件

> @src/auth/middleware.ts 解释一下这个中间件的作用

> @package.json 我们项目有哪些主要依赖？

> @README.md 根据这个 README，总结项目的主要功能

支持的文件类型：

  • 文本文件（.ts/.js/.java/.py/.md/.json/.yaml 等）
  • 图片文件（.png/.jpg/.gif/.webp）—— 以视觉方式呈现给 Claude
  • PDF 文件（.pdf）—— 注意大 PDF 会消耗大量 token
  • Jupyter Notebook（.ipynb）

引用多个文件

> @src/components/Button.tsx @src/components/Input.tsx
  这两个组件的 props 接口风格一致吗？

> @src/api/order.ts @src/services/orderService.ts @src/types/order.ts
  这三个文件共同构成了订单模块，帮我分析模块架构

注意：引用多个文件会累加 token 消耗，建议只引用真正需要的文件。

引用目录

> @src/utils/ 这些工具函数有哪些是重复的逻辑？

> @src/components/ 列出所有组件，分析它们的命名是否统一

注意：引用整个目录会引入目录下所有文件的内容，极其消耗 token。建议：

  • 只对小目录（< 5 个小文件）使用目录引用
  • 大目录改用 Glob + 精确 Read

引用 CLAUDE.md 中的外部配置（@引用语法）

在 CLAUDE.md 文件中，@ 用于引入外部配置文件：

# ~/.claude/CLAUDE.md

# 引入团队共享配置
@~/Documents/git/team-knowledge/shared-config/CLAUDE.md

# 引入项目 API 约定文档
@./docs/api-conventions.md

# 引入组件开发规范
@./docs/component-guidelines.md

这里的 @ 行为与对话中不同：

  • 对话中的 @：实时读取文件内容加入当前消息
  • CLAUDE.md 中的 @：文件内容被合并到 CLAUDE.md 的上下文，每次对话都加载

引用 URL

> @https://docs.example.com/api 根据这个文档更新代码中的 API 调用

> @https://github.com/user/repo/blob/main/README.md 这个库怎么用？

注意：

  • 公司内网环境通常无法访问外部 URL
  • 内部系统（如内网 SDoc、Axure）通过 Chrome DevTools MCP 访问更可靠
  • URL 内容会被转换为 Markdown，可能丢失部分格式

路径规则

相对路径 vs 绝对路径

# 相对路径（相对于当前工作目录）
@src/auth.ts
@./docs/api.md
@../shared/utils.ts

# 绝对路径
@/Users/yourname/project/src/auth.ts

# 家目录缩写
@~/Documents/cotti/DCP操作文档/1.0.0/DCP操作文档.md

路径中有空格

# 如果路径包含空格，用引号包裹
@"src/My Component/index.tsx"

引用失败时的行为

情况Claude 的行为
文件不存在提示错误，不会停止对话
文件无读取权限提示权限问题
URL 无法访问提示网络错误，跳过该引用
目录为空提示目录为空
文件太大截断到最大行数（约 2000 行）

Token 消耗对比

引用方式               Token 消耗

@src/auth.ts           整个文件大小（可能很大）
@src/auth.ts（50行）    约 200 tokens
@src/                  目录下所有文件之和（极大）
@URL                   网页转 Markdown 后的大小

优化方式：
1. 先 Grep 定位行号
2. 再 @文件名 + 明确告知关注范围
   > @src/auth.ts 我只关心 validateToken 函数（第 80-120 行）

最佳实践

1. 精确引用而非泛泛引用

# 不推荐（token 消耗大）
> @src/services/ 分析所有服务

# 推荐（先定位，再精确）
> 先列出 src/services/ 下有哪些文件
（看完列表后）
> @src/services/OrderService.ts 分析订单服务的架构

2. 在 CLAUDE.md 中合理使用 @

# 主 CLAUDE.md（保持简短）
## 技术栈
- React 18 + TypeScript

## 禁止行为
- 禁止使用 shineout

# 详细规范按需引用（不要全部加载）
@./docs/component-guidelines.md   ← 开发组件时需要
@./docs/api-conventions.md        ← 开发接口时需要

3. 多文件分析时控制范围

# 同时引用多个文件时，告诉 Claude 重点关注什么
> @src/api/order.ts @src/types/order.ts
  重点：检查这两个文件的类型定义是否对齐，
  特别是 OrderStatus 枚举的值

与工具调用的区别

@文件路径（对话语法）Read 工具
使用者你（在消息中）Claude（自动选择）
时机消息发送前读取Claude 决策后读取
控制你控制读什么Claude 自动判断读什么
精确度整个文件可以指定 offset+limit

结论：当你明确知道需要某个文件时用 @；让 Claude 自己决定读什么时，让它用 Read 工具（通常更节省 token）。

avatar
文章
阅读
粉丝