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/codegraphCodeGraph 默认零配置语言识别完全由文件扩展名自动完成开箱即用地跳过依赖、构建与缓存目录并读取.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.tsloadParsedConfig()以项目根目录 文件 mtime为缓存键只要文件没被修改重复调用只花一次statmtime 变化即重新解析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/TSnode_modules、.yarn、.pnpm-store、.next、.turbo、.vercel等、Python__pycache__、.venv、.mypy_cache、.tox、Rust/JVMtarget、.gradle、.NETobj、Go/PHP/Ruby 的vendor、Swift/iOSPods、Carthage、DerivedData、.build、Dart.dart_tool、.pub-cache、Lualua_modules、.luarocks等生态。源码注释特意强调两点这套排除不需要.gitignore存在也生效——即使你的项目根本没有.gitignorenode_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库编译成 matcherloadExcludeMatcher见 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 中得到印证每个值必须是一个支持的语言 idisLanguageSupported校验用户映射叠加在内建扩展表之上、冲突时用户优先detectLanguage中先查 overrides 再查EXTENSION_MAP所以你也可以重指内建扩展例如.h: cpp建议把文件提交进版本库让团队共享同一份映射写错的语言名或格式错误的条目只会被警告并跳过——从不导致索引失败没有codegraph.json的项目行为与从前完全一致从源码结构看还有一层键规范化normalizeExtKeysrc/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 路径还封装了addIncludeIgnoredPatternssrc/project-config.ts可在用户确认后把模式幂等地追加进已有codegraph.json并保留其他键若现有文件不是合法 JSON 则拒绝覆写并提示手工修复。修改includeIgnored后执行codegraph index。完整字段速查含源码已支持的 deprioritize汇总当前codegraph.json的全部合法字段字段类型作用生效范围extensions对象.ext→ 语言 id为支持的语言指定自定义/重指扩展名语言检测detectLanguageexcludegitignore 模式数组排除路径——即使已被 git 跟踪全量索引、sync、watchincludegitignore 模式数组强制纳入被.gitignore排除的第一方源码全量索引、sync、watchincludeIgnoredgitignore 模式数组进入被忽略目录索引其中的嵌套 git 仓库内嵌仓库发现与索引deprioritizegitignore 模式数组路径仍被索引、可被搜到但不得在搜索排序中压过第一方代码搜索排序前四个字段是文档明示的配置面第五个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。修改配置的完整操作流把上面所有字段的共同收尾步骤串起来在项目根目录创建或编辑codegraph.json可选纯 JSON无注释——带注释的JSON会整体解析失败并降级为零配置保存后执行codegraph index重新索引codegraph index --force用于彻底重建增量同步与文件监听路径会自动读取新配置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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考