Claude Context 的索引机制的核心规则只有一条公式：最终索引文件 = 支持的扩展名 − 忽略规则。扩展名和忽略规则都是「叠加」的——默认值 + 平台传入参数 + 环境变量 + .gitignore 各自叠加，不是互相覆盖。索引过程是异步的：发完索引指令立刻返回，后台处理；进度百分比是「阶段式」而非「线性」的，跳到 10% 很正常，不代表只处理了 10% 的文件。

Claude Context 索引机制详解：哪些文件会被索引，异步流程怎么运作

安装完 Claude Context 之后，你可能会发现：索引进度很快就跳到 10%，然后长时间不动。或者索引完成后状态显示「0 files, 0 chunks」。要理解这些现象，需要先理解两个核心机制：文件过滤规则和异步索引流程。

文件过滤规则

Claude Context 决定「索引哪些文件」的方式比想象中简单，核心只有一条公式：

最终索引文件 = (所有支持的扩展名) − (所有忽略规则)

扩展名是「叠加」的，忽略规则也是「叠加」的，各个来源不是覆盖关系。

扩展名来源（叠加）

来源	怎么设	示例
默认扩展名	内置	.ts、.tsx、.js、.py、.java、.go、.rs、.md 等
MCP 参数	对 AI 说「索引时包含 .vue 文件」	customExtensions: [".vue"]
环境变量	CUSTOM_EXTENSIONS=.vue,.svelte	全局生效

三个来源的扩展名会合并在一起，不是三选一。默认不索引 Vue 文件，你加上 .vue，它就变成默认扩展名 + .vue，而不是只有 .vue。

实际上，你可以在索引时直接对 AI 说：

Index this codebase, and include .vue, .svelte, .astro files

AI 会自动把 customExtensions 参数传给 Claude Context。

忽略规则来源（叠加）

来源	说明
默认忽略规则	内置，覆盖 node_modules、dist、.git、.env、缓存目录等常见模式
MCP 参数	对 AI 说「排除 temp/** 和 private/**」
环境变量	CUSTOM_IGNORE_PATTERNS=temp/**,*.backup
.gitignore	项目根目录的 .gitignore 自动生效
.xxxignore 文件	.cursorignore、.codeiumignore、.contextignore 等
全局 .contextignore	~/.context/.contextignore，对所有项目生效

所有来源的规则都会合并，逐条过滤。这意味着：

• .gitignore 里的 node_modules/ 已经排除了该目录
• 你不需要在环境变量里再写一遍 node_modules
• 但如果 .gitignore 漏掉了某个目录，你可以在 CUSTOM_IGNORE_PATTERNS 里补充

为什么你不需要关心默认扩展名

默认扩展名覆盖了大部分主流编程语言和文档格式。你通常只需要关心「默认没覆盖的文件」，比如 Vue、Svelte、Astro、自定义模板文件。

默认忽略规则已经处理了 node_modules、dist、.git、.env 等不需要索引的内容。你只需要补充项目特有的排除目录。

---

异步索引流程

Claude Context 的索引不是阻塞式的。当你对 AI 说 Index this codebase 时，Claude Context 立刻返回「索引已启动」，实际处理在后台进行。

状态流转

索引任务有四种状态：

状态	含义	说明
indexed	索引完成，可正常搜索	绿色
indexing	正在后台处理	进行中
indexfailed	索引失败	可重试
not_found	该路径从未索引过	需要先执行索引

索引期间你可以随时搜索，搜索结果会包含已索引的部分——不必等全部完成。

进度百分比为什么会跳

这是最让人困惑的部分。get_indexing_status 返回的百分比是「阶段式」的，不是「X% 文件已完成」的线性进度。

大致阶段划分：

百分比	阶段
0%	准备集合、验证前置条件
~5%	扫描代码库，构建文件列表
10% → 100%	逐批处理文件：切块 → 生成向量 → 写入数据库
100%	索引完成

所以：

• 跳到 10% 很正常：它代表的是「从准备阶段进入处理阶段」，不是只处理了 10% 的文件
• 在 10% 停很久也很正常：10%~100% 阶段是真正的批量处理，大项目可能跑几十分钟
• 进度不是实时更新：进度会定期写入本地快照文件 ~/.context/mcp-codebase-snapshot.json，快速完成的阶段可能表现为跳跃

多代码库路径隔离

Claude Context 用绝对路径标识代码库。这意味着：

• 用绝对路径 /home/user/project-a 索引了一次
• 用符号链接 /home/user/link-to-a 又索引了一次
• 这会被当作两个独立的代码库

如果你发现索引了但搜索无结果，先确认 search_code 用的路径和 index_codebase 是完全一致的绝对路径。

---

代码是怎么被切块的

把代码切块（chunking）是索引的关键步骤。Claude Context 提供两种切块策略：

AST Splitter（推荐）

基于语法树切块，按代码的逻辑结构分割。函数、类、接口会各自成为独立的块，不会在函数中间断开。

优势：切出来的块语义更完整，搜索结果更精确。

适合：大部分项目，特别是代码结构清晰的项目。

LangChain Splitter

基于字符数量切块，按固定长度切分，相邻块之间有重叠（默认 200 字符）。

优势：处理速度更快，对任何文件类型都适用。

适合：非代码文件，或者不关心切块质量、只追求速度的场景。

选择方式：在配置里设置 SPLITTER_TYPE=ast 或 SPLITTER_TYPE=langchain，默认是 ast。

---

索引数据存在哪里

索引结果主要存在两个地方：

1. 向量数据库（Zilliz Cloud / 本地 Milvus）：存储代码片段的向量，用于搜索
2. 本地快照 ~/.context/mcp-codebase-snapshot.json：记录每个代码库的索引状态、文件数、chunk 数等元数据

当你执行 clear_index 时，会同时清除向量数据库中的集合和本地快照记录。

---

常见现象解读

现象	原因	解决办法
进度跳到 10% 后不动	10%~100% 是批量处理阶段，大项目正常	等待，或看 debug 日志确认是否在处理
状态显示 0 files, 0 chunks	本地快照元数据过时	clear_index → 重新 index_codebase
搜索结果少	可能被忽略规则过滤，或扩展名没覆盖	检查 .gitignore 和 CUSTOM_EXTENSIONS
同一项目搜索无结果	路径不一致（绝对路径 vs 相对路径）	确认搜索和索引用的是同一个绝对路径
索引失败	Embedding API Key 问题，或向量数据库连接失败	检查 Key 是否有效、Zilliz 集群是否正常

如果上述方法都没解决问题，可以参考 常见问题与排查指南 的系统性排查步骤。

---

FAQ

Q: 索引大项目需要多久？ A: 取决于文件数量、Embedding Provider 的吞吐量和批次大小。几千个文件的项目通常在几分钟到十几分钟之间。VoyageAI 和 Gemini 通常比 OpenAI 快一些。调大 EMBEDDING_BATCH_SIZE（默认 100）可以加速。

Q: 索引期间搜索结果准不准？ A: 准确度取决于已索引的部分。索引过程中搜索使用的是已处理的代码片段，完整度会逐渐提高。建议等 indexed 状态后再做关键判断。

Q: 我修改了代码，需要重新索引全部吗？ A: Claude Context 没有增量索引机制。修改代码后，需要 clear_index 清除旧索引，再 index_codebase 重新索引。因为依赖后台代码同步机制，MCP 模式下通常由 AI Agent 负责判断是否需要重新索引。