CodeGraph 配置实战：零配置默认行为与 codegraph.json 全字段详解

CodeGraph 配置实战：零配置默认行为与 codegraph.json 全字段详解

【免费下载链接】codegraphPre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, CoPilot, and Hermes Agent — fewer tokens, fewer tool calls, 100% local项目地址: https://gitcode.com/GitHub_Trending/co0degr/codegraph

CodeGraph 默认零配置：语言识别完全由文件扩展名自动完成，开箱即用地跳过依赖、构建与缓存目录，并读取.gitignore决定哪些文件不进索引。当你需要把已提交的 vendor 目录踢出图、把只由 SVN/Perforce 管理的源码拉进图、或给.tpl这类非标准扩展名指定语言时，唯一要写的文件就是项目根目录的可选codegraph.json。读完本文，你将掌握codegraph.json的每个字段（exclude、include、includeIgnored、extensions）的适用场景、gitignore 风格模式写法、优先级规则，以及从源码层面确认的解析、缓存与容错机制。

零配置：不写任何文件也能正常工作

CodeGraph 的设计前提是"几乎不需要配置"：语言支持从文件扩展名自动推断，没有需要逐语言接线的步骤。项目中可以完全没有codegraph.json，行为与默认完全一致——这一点在加载器实现中是显式保证的：配置文件缺失、JSON 非法、某个字段类型错误，任何一种失败模式都会降级为"零配置默认"，只会打警告，绝不抛错中断索引。

从源码结构看，配置加载集中在 src/project-config.ts：

• 配置文件名常量PROJECT_CONFIG_FILENAME = 'codegraph.json'，只从项目根目录解析（src/project-config.ts）；
• loadParsedConfig()以"项目根目录 + 文件 mtime"为缓存键：只要文件没被修改，重复调用只花一次stat；mtime 变化即重新解析（src/project-config.ts）。多项目共存的守护进程场景下按根目录隔离缓存，互不串扰；
• 每个字段都有独立的加载函数：loadExtensionOverrides、loadExcludePatterns、loadIncludePatterns、loadIncludeIgnoredPatterns、loadDeprioritizePatterns，均共享同一次解析结果。

这个 mtime 缓存机制意味着：编辑codegraph.json后，下一次索引/同步/扫描操作会自动看到新值，不需要重启 MCP 服务；而数据库类查询路径（如搜索排序）也通过同一个 mtime 缓存读取最新模式。

开箱即用的跳过规则

在讨论如何"多加排除"之前，先明确默认就跳过什么。以下三条来自官方文档的描述，均能在源码中得到逐条印证：

1. 依赖、构建、缓存目录——node_modules、vendor、dist、build、target、.venv、Pods、.next等。这一整套名单在 src/extraction/index.ts 的DEFAULT_IGNORE_DIRS中硬编码，覆盖 JS/TS（node_modules、.yarn、.pnpm-store、.next、.turbo、.vercel等）、Python（__pycache__、.venv、.mypy_cache、.tox）、Rust/JVM（target、.gradle）、.NET（obj）、Go/PHP/Ruby 的vendor、Swift/iOS（Pods、Carthage、DerivedData、.build）、Dart（.dart_tool、.pub-cache）、Lua（lua_modules、.luarocks）等生态。源码注释特意强调两点：

• 这套排除不需要.gitignore存在也生效——即使你的项目根本没有.gitignore，node_modules也不会进图；
• 刻意没有收录packages、lib、app、src、bin这类容易混入第一方源码的通用目录名，宁可少排也不误伤真实代码。

2..gitignore中的内容——在 git 仓库里通过 git 本身遵守，在非 git 项目里则直接读取根目录和嵌套的.gitignore文件（读取逻辑对非 UTF-8、包含无法编译为正则的行做了容错，坏行丢弃、整体继续，见 src/extraction/index.ts）。

3. 大于 1 MB 的文件——src/extraction/index.ts 中MAX_FILE_SIZE = 1024 * 1024。生成的打包产物、压缩 JS、vendored 大文件没有可用符号，只会白白消耗 WASM 堆和 worker 预算，因此直接跳过；跳过时索引结果中会带一条size_exceeded警告级记录，而不是静默丢弃。

此外源码中还有两类文档未展开的默认跳过：Android 资源目录（res/layout/、res/drawable/等，见 src/extraction/index.ts）以及 CodeGraph 自己的数据目录（.codegraph/，通过 src/directory.ts 的isCodeGraphDataDir匹配，防止 Windows + WSL 双环境互看对方索引时把索引文件本身扫进去）。

用 .gitignore 排除更多、或把默认排除的拉回来

最常见的调整其实不需要codegraph.json：

• 想把某个目录排除：直接加进.gitignore；
• 想把某个默认被排除的目录拉回来（比如你确实要索引一个 vendored 依赖）：加一条否定规则，如!vendor/。

由于内置跳过规则统一适用（无论是否 git、无论是否已跟踪），提交一个依赖或构建目录到仓库也不会把它强塞进图——.gitignore否定规则是唯一显式的"拉回"入口。

exclude：排除已被 git 跟踪的目录

.gitignore只能影响 git尚未跟踪的文件——它无法剔除你已经提交的目录。这正是文档给出的典型场景：一个被 check-in 的 Metronic 管理端主题放在static/下，里面有几百个.js文件，.gitignore对它无能为力。这类情况交给codegraph.json的exclude：

{ "exclude": ["static/", "**/vendor/**"] }

语义要点（每条都有源码/测试依据）：

• 每个条目是gitignore 风格模式，针对项目根相对路径匹配："static/"这样的目录、"**/vendor/**"双星通配、单个文件路径都可用；
• 在 CodeGraph 查看所有文件的地方全面生效——全量索引、增量sync、文件监听（watcher）三条路径一致；
• 对已跟踪文件同样生效（这正是它的存在意义），且优先级高于一切其他规则；
• 它与includeIgnored方向相反：includeIgnored是把被忽略的嵌套仓库拉进图，exclude是把内容踢出图。

底层实现上，模式数组经由ignore库编译成 matcher（loadExcludeMatcher，见 src/extraction/index.ts），在 git 枚举路径和非 git 文件系统遍历路径上都做过滤。tests/exclude-config.test.ts 验证了核心不变量：已跟踪的static/目录在写入exclude后确实从扫描结果消失而app/main.ts保留；**/vendor/**双星通配在多个packages/*/vendor/下生效；加载器对非数组值、空白条目、非法 JSON 一律"警告并降级为空列表"。

修改exclude后需要重新索引：codegraph index（完整重扫；codegraph index --force从头重建，参见 索引指南）。

include：把被 .gitignore 排除的第一方源码纳入索引

.gitignore让文件不进索引——通常这正是你想要的，除非被忽略的文件是真实的第一方源码。文档给出的动机场景是：项目由SVN、Perforce 或其他 VCS 与 Git 并行管理，一部分源码提交给那个 VCS，并被有意写进.gitignore以保证绝不落入 Git。这份源码依然是你的，也理应进图，但 git 从不列出它们，CodeGraph 也就永远看不到（includeIgnored帮不上——它只复活被忽略目录里内嵌的 git 仓库，不覆盖普通源码）。

在codegraph.json的include下列出这些路径，强制纳入：

{ "include": ["Tools/", "Local/typescript/"] }

工作方式与规则：

• 条目同样是 gitignore 风格模式，针对项目根相对路径：目录如"Tools/"、递归通配"Tools/**"、单个文件都可以；
• CodeGraph直接扫盘发现匹配文件（覆盖.gitignore），并在全量索引、增量sync与文件监听三处一致索引它们；
• 明确写出的exclude仍然优先——同一路径同时出现在两者中时保持排除；
• 内置跳过的目录（node_modules、dist、.git等）永远不会被include复活，即使模式能匹配进它们内部；
• 方向上它是exclude的镜像：exclude让被跟踪的文件留在图外，include则是让 git 本身从不跟踪的源码进入图内。

修改include后同样执行codegraph index重新索引。

extensions：为支持的语言指定自定义文件扩展名

当项目对某个受支持语言使用非标准扩展名——例如 Lua 写作.dota_lua、PHP 模板写作.tpl——这些文件默认会被跳过，因为扩展名不在识别表中。用项目根目录的codegraph.json映射它们：

{ "extensions": { ".dota_lua": "lua", ".tpl": "php" } }

行为细节，均可在 src/project-config.ts 与 src/extraction/grammars.ts 中得到印证：

• 每个值必须是一个支持的语言 id（isLanguageSupported校验）；
• 用户映射叠加在内建扩展表之上、冲突时用户优先（detectLanguage中先查 overrides 再查EXTENSION_MAP），所以你也可以重指内建扩展，例如".h": "cpp"；
• 建议把文件提交进版本库，让团队共享同一份映射；
• 写错的语言名或格式错误的条目只会被警告并跳过——从不导致索引失败；没有codegraph.json的项目行为与从前完全一致；
• 从源码结构看还有一层键规范化（normalizeExtKey，src/project-config.ts）：键会被 trim、小写化并补点（"foo"→".foo"），而空键、多点键（如".d.ts"——语言检测只看最后一段扩展名）、含路径分隔符的键会被判定为"永不匹配"并警告跳过。

修改映射后执行codegraph index重新索引。

includeIgnored：索引嵌套的 git 仓库

CodeGraph 尊重.gitignore，因此被 gitignore 的目录会整体留在图外——包括嵌套在它里面的 git 仓库。如果你在某个 gitignored 目录里放克隆的参考项目、vendored 副本或一堆无关仓库（resource/、.repos/、examples/之类），CodeGraph 默认不进去、不发现内嵌仓库、不索引。

相反，如果你维护的是一个"独立克隆仓库的超级仓库"——工作区自身的.gitignore列出各子仓库以保持git status干净，而你确实希望每个子仓库都进同一张图——用includeIgnored显式把它们拉回：

{ "includeIgnored": ["packages/", "services/"] }

• 每个条目是 gitignore 风格模式，命名一个"其中的嵌套 git 仓库应当被索引"的被忽略目录；
• CodeGraph 会进入你列出的目录，按每个内嵌仓库自己的git ls-files分别索引，因此每个子仓库各自的.gitignore依然被遵守；
• 未列出的目录保持排除。

需要知道的边界条件：

• 未被跟踪的嵌套仓库（没有被 gitignore 的）本来就自动索引——includeIgnored只针对被.gitignore排除的那些；
• 内置跳过的node_modules等目录永远不会被复活，即使在已 opt-in 的目录内部；
• 不具备这种布局的项目完全不需要codegraph.json。

加载器单测见tests/include-ignored-config.test.ts，多仓库工作区的行为级验证（扫描、内嵌仓库发现、同步）在tests/multi-repo-workspace.test.ts。此外源码中的 CLI 路径还封装了addIncludeIgnoredPatterns（src/project-config.ts）：可在用户确认后把模式幂等地追加进已有codegraph.json并保留其他键；若现有文件不是合法 JSON 则拒绝覆写并提示手工修复。修改includeIgnored后执行codegraph index。

完整字段速查（含源码已支持的 deprioritize）

汇总当前codegraph.json的全部合法字段：

前四个字段是文档明示的配置面；第五个deprioritize目前未在站点文档中展开，但从 src/project-config.ts 的字段定义和tests/deprioritize-config.test.ts 可以确认它已是受支持的字段：当项目里某个只有团队才知道的周边目录（如optional-skills/、scripts/）含有与生产代码同名的通用符号、在精确名匹配下挤占真实答案时，用deprioritize让"内容留在图里、只是不再赢"——它是exclude（召回杠杆，内容彻底离开索引）的排序学对应物，内置的 example/sample/fixture/benchmark 降权规则的扩展版。使用方式与上表一致：gitignore 风格模式数组，针对项目根相对路径。

所有字段的共同容错约定：非数组值、非字符串/空白条目、写错的语言 id、非法 JSON——一律"警告 + 跳过该条目"，加载器永不抛异常，配置错误最坏的结果是"当作没写"。

数据放在哪里

每个项目的数据存放在项目根目录的.codegraph/目录中，其中包含 SQLite 数据库codegraph.db。一切都在本地，没有任何数据离开你的机器（隐私性设计说明见 TELEMETRY.md）。从源码结构看还有两个相关细节：

• 初始化时 CodeGraph 会在.codegraph/内自动写入一个.gitignore，内容是全目录通配忽略（*+!.gitignore），保证数据库、daemon.pid、socket、日志等瞬态文件永远不会进入版本库（src/directory.ts）；
• 数据目录名本身可用环境变量CODEGRAPH_DIR覆盖（须是单个纯目录名，如CODEGRAPH_DIR=.codegraph-win），其动机是 Windows 原生与 WSL 共享同一工作树时让两个环境各持一份索引，避免跨 WSL2/Windows 文件系统边界的 SQLite 锁竞争（src/directory.ts）。

修改配置的完整操作流

把上面所有字段的共同收尾步骤串起来：

1. 在项目根目录创建或编辑codegraph.json（可选，纯 JSON，无注释——带注释的"JSON"会整体解析失败并降级为零配置）；
2. 保存后执行codegraph index重新索引（codegraph index --force用于彻底重建）；
3. 增量同步与文件监听路径会自动读取新配置（mtime 缓存命中变更即重解析），无需重启已运行的 MCP 服务。

相关文档延伸阅读：安装、快速开始、支持语言、CLI 参考。

【免费下载链接】codegraphPre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, CoPilot, and Hermes Agent — fewer tokens, fewer tool calls, 100% local项目地址: https://gitcode.com/GitHub_Trending/co0degr/codegraph