Claude Context 决定最终索引文件的核心公式是：最终文件 = 所有支持的文件扩展名 - 所有忽略模式。这一规则链通过合并多个来源的配置（如默认设置、MCP 自定义参数、环境变量及 .gitignore 等文件）来精确控制代码库的索引范围，确保语义搜索的准确性与效率。

Claude Context 忽略规则详解：文件包含与排除的完整规则链

在使用 Claude Context 为 AI 编程助手提供语义代码搜索能力时，一个关键问题是：哪些文件会被索引？ 这个问题的答案由一套清晰的规则链决定，它确保了索引过程的精确性和可控性。本文将深入解析这套规则，帮助你理解并优化 Claude Context 的文件索引行为。

核心公式：最终文件的选择逻辑

Claude Context 的文件选择遵循一个简单而强大的公式：

最终索引文件 = (所有支持的文件扩展名) - (所有忽略模式)

这意味着，一个文件必须同时满足两个条件才能被索引：

文件扩展名必须在“支持扩展”列表中。
文件路径不能匹配任何“忽略模式”。

接下来，我们将分别拆解“支持扩展”和“忽略模式”这两个集合是如何构建的。

支持扩展的来源（加法合并）

支持的扩展名列表通过加法合并三个来源构建，所有来源的扩展都会被汇总，并去除重复项。

默认扩展：Claude Context 内置了一套广泛支持的文件类型。在核心引擎包 @zilliz/claude-context-core 的 context.ts 文件中，DEFAULT_SUPPORTED_EXTENSIONS 数组定义了这些默认扩展：

const DEFAULT_SUPPORTED_EXTENSIONS = [
    // Programming languages
    '.ts', '.tsx', '.js', '.jsx', '.py', '.java', '.cpp', '.c', '.h', '.hpp',
    '.cs', '.go', '.rs', '.php', '.rb', '.swift', '.kt', '.scala', '.m', '.mm',
    '.dart', '.sol',
    // Text and markup files
    '.md', '.markdown', '.ipynb',
    // '.txt',  '.json', '.yaml', '.yml', '.xml', '.html', '.htm',
    // '.css', '.scss', '.less', '.sql', '.sh', '.bash', '.env'
];

该列表覆盖了主流编程语言、文档以及 Jupyter Notebook 文件。

MCP 自定义扩展：通过在调用 MCP 工具（如 index_codebase）时传递 customExtensions 参数，你可以动态添加需要索引的文件类型。例如，告诉 AI 助手：“索引这个代码库，并包含 .vue、.svelte、.astro 文件”。
环境变量扩展：通过设置 CUSTOM_EXTENSIONS 环境变量（例如 export CUSTOM_EXTENSIONS=".vue,.svelte,.astro"），可以持久地添加自定义扩展。这在配置 MCP 服务器环境变量时非常有用。

忽略模式的来源（加法合并）

忽略模式的构建更为复杂，它同样通过加法合并来自六个不同来源的规则，所有来源的模式都会被汇总。

默认忽略模式：DEFAULT_IGNORE_PATTERNS 数组定义了需要排除的常见目录和文件，包括构建产物（node_modules/**、dist/**）、IDE 配置（.vscode/**、.idea/**）、版本控制目录（.git/**）、缓存文件（__pycache__/**）等。
```
const DEFAULT_IGNORE_PATTERNS = [
    // Common build output and dependency directories
    'node_modules/**',
    'dist/**',
    'build/**',
    'out/**',
    'target/**',
    'coverage/**',
    '.nyc_output/**',
    // ... (其他模式)
];
```
这些模式确保了像 node_modules 这样的庞大且无关的目录不会被纳入索引。
MCP 自定义忽略模式：通过 ignorePatterns 参数动态传递。例如，命令 “索引此代码库，并排除 temp/**、*.backup、private/** 文件”。
环境变量忽略模式：通过 CUSTOM_IGNORE_PATTERNS 环境变量设置，例如 export CUSTOM_IGNORE_PATTERNS="temp/**,*.backup,private/**"。
.gitignore 文件：Claude Context 会自动读取代码库根目录下的 .gitignore 文件，并将其包含的模式作为忽略规则。这是与 Git 工作流保持一致的重要机制。
.xxxignore 文件：任何位于代码库根目录、文件名匹配 .xxxignore 模式的文件（例如 .cursorignore、.codeiumignore、.contextignore）都会被自动加载。
全局 .contextignore 文件：位于用户主目录下的 ~/.context/.contextignore 文件。其中的规则会在所有代码库索引时生效，适合设置个人的全局排除规则。

规则隔离性：一个关键测试用例

规则链的设计保证了不同代码库和请求之间的配置隔离。测试文件 ignore-patterns.test.ts 中的用例 'does not leak file-based ignore patterns between codebases' 直观地展示了这一点：

it('does not leak file-based ignore patterns between codebases', async () => {
    const projectA = path.join(tempRoot, 'project-a');
    const projectB = path.join(tempRoot, 'project-b');
    await fs.mkdir(projectA);
    await fs.mkdir(projectB);
    await fs.writeFile(path.join(projectA, '.contextignore'), '*.md\n');

    const context = new Context({ vectorDatabase: createVectorDatabase() });

    const projectAIgnores = await context.getEffectiveIgnorePatterns(projectA);
    expect(projectAIgnores).toContain('*.md'); // Project A 有自己的规则

    const projectBIgnores = await context.getEffectiveIgnorePatterns(projectB);
    expect(projectBIgnores).not.toContain('*.md'); // Project B 不受影响
});

该测试确保为 projectA 添加的 .contextignore 规则不会“泄漏”到 projectB 的索引过程中。每次索引都会重新计算当前代码库的有效规则。

文件包含流程与特殊行为

结合以上规则，完整的文件包含流程如下：

构建最终的支持扩展名列表。
构建最终的忽略模式列表。
递归遍历代码库目录。
对于每个文件，先检查其路径是否匹配忽略模式，如果匹配则跳过。
再检查其扩展名是否在支持列表中，如果在则加入待索引列表。

在遍历过程中，还有两个重要的自动行为：

1. Leading-slash 目录模式的根锚定行为

在 .gitignore 或 .contextignore 中，以斜杠开头的模式（如 /Library/）被认为是根锚定的。它只匹配代码库根目录下的同名目录，而不会匹配子目录中的同名目录。

测试用例 'treats leading-slash directory ignore patterns as root-anchored and recursive during indexing' 验证了这一行为：

// .gitignore 文件内容: "/Library/"
// 文件结构:
// project/
//   Library/generated.md  -> 会被忽略（匹配根目录的 /Library/）
//   src/Library/nested.md -> 不会被忽略（是子目录下的 Library）
//   src/keep.md           -> 会被索引

索引结果将只包含 src/Library/nested.md 和 src/keep.md。

2. 点文件/点目录的自动跳过

Claude Context 在遍历目录时，会自动跳过所有以点（.）开头的文件和目录（即点文件和点目录，如 .config、.github、.env 文件）。这是一个内置的安全机制，即使这些文件/目录没有出现在显式的忽略列表中，也不会被索引。

测试用例 'skips dotfiles and dot directories during initial indexing' 清楚地展示了这一点：根目录下的 .hidden.md、.config/、.github/ 以及 src/ 下的 .cache/ 目录及其内容都不会被索引，只有 src/keep.md 被包含。

配置示例与最佳实践

场景：你想索引一个 Vue.js 项目，但希望排除测试文件和临时构建产物。

解决方案：

添加 Vue 扩展：在 MCP 调用中传递 customExtensions: [".vue"]，或设置环境变量 CUSTOM_EXTENSIONS=".vue"。
添加忽略规则：
- 在代码库根目录创建 .contextignore 文件，写入：
```
tests/
*.test.js
*.spec.ts
```
- 或者，在 MCP 调用中传递 ignorePatterns: ["tests/", "*.test.js", "*.spec.ts"]。
利用默认规则：node_modules、dist 等目录会被 DEFAULT_IGNORE_PATTERNS 自动排除，无需重复配置。

FAQ

Q: 如何只索引特定语言的文件，比如只索引 Python？ A: 你需要同时做两件事：1) 在 DEFAULT_SUPPORTED_EXTENSIONS 基础上，通过 MCP 或环境变量只添加 .py 扩展名；2) 通过自定义忽略模式排除所有其他编程语言的扩展名。一个更简单的方法是，在对话中直接告诉 AI 助手：“只索引这个代码库的 Python 文件”。

Q: 我在 .gitignore 里排除了 docs/，为什么 Claude Context 还是索引了它？ A: 请检查 docs/ 目录下是否有以点开头的子目录或文件（如 .vuepress、.gitkeep）。Claude Context 会自动跳过点文件/点目录，但不会自动跳过其父目录 docs/。如果 .gitignore 中的 docs/ 规则生效，docs/ 目录本身及其内容都会被跳过。如果问题依旧，请确认 Claude Context 有权限读取 .gitignore 文件。

Q: ~/.context/.contextignore 全局文件中的规则优先级如何？ A: 全局 .contextignore 的规则与代码库本地的 .gitignore、.contextignore 等文件中的规则平级合并，共同构成最终的忽略模式列表。如果存在冲突，会因为加法合并而同时生效（即更严格的规则会起作用）。它不会覆盖本地规则。

Claude Context 忽略规则详解：文件包含与排除的完整规则链 #

核心公式：最终文件的选择逻辑 #

支持扩展的来源（加法合并） #

忽略模式的来源（加法合并） #

规则隔离性：一个关键测试用例 #

文件包含流程与特殊行为 #

1. Leading-slash 目录模式的根锚定行为 #

2. 点文件/点目录的自动跳过 #

配置示例与最佳实践 #

FAQ #