CIndex
免编译的 C/C++ 全局代码索引,SourceInsight 重度用户的平替 —— 跳转定义、调用关系、符号浏览与同名高亮。
为什么用 CIndex
- 零依赖,开箱即用 —— 不需要先构建工程、不需要编译数据库,也不依赖任何第三方工具链。头文件、未参与构建的代码段、跨平台条件编译的各个分支,一样能索引。
- 大工程扛得住 —— 千万行级源码、近百万符号,单机可索引,常驻内存约 0.45 KB / 符号。
- 快 —— 跳转约 7 ms;首次全量分钟级;增量亚秒级;重启免重建。
- 后台不打扰 —— 索引全程在后台跑,CPU 占用、线程数、进程优先级都可限,写代码时感觉不到它在工作。
性能实测
真实工程、单机 8 线程实测。工作量:A = 28,153 个 C/C++ 文件 / 988,668 个符号 / 1,375,921 条调用边;B = 21,925 个文件 / 820,789 个符号 / 1,007,253 条调用边。
| 指标 |
实测 |
| 首次全量建索引(A) |
64 ~ 99 秒 |
| 无改动重新同步(A) |
0.57 秒 |
| 改动 1 个文件后同步(A) |
0.62 秒 |
| 跳转定义响应(A) |
约 7 ms |
| 重启恢复快照(B) |
1.9 秒 |
| 索引快照体积(B) |
337 MB |
| 索引后常驻内存(B) |
315 MB(≈ 0.45 KB / 符号) |
- 改一个文件与什么都不改一样快 —— 都是亚秒级,不会因为你多存了一次盘就等半天。
- 个别超大文件不会拖住整轮同步 —— 工程 A 里有 11 个超大生成头文件被自动跳过,整轮同步照常完成,被跳过的文件会记进运行日志。
功能
跳转定义
Ctrl/Cmd + 左键 或 F12,直接落到真实定义处。
- 函数落到实现,类型落到定义所在的头文件 —— 只有声明的地方会继续找定义。
- 覆盖函数、方法、结构体 / 类 / 联合 / 枚举标签、
typedef、using 别名、宏、命名空间成员、类成员、文件级变量;头文件里同样能跳转。
- 同一份头文件在工程里有多个副本时优先跳到「正本」;常见名字在多个作用域重复时按作用域与引用上下文消歧;同一个定义只给一个候选,不会弹出一堆重复项。
- 认继承链 —— 点派生类里没有声明的成员(继承来的方法 / 字段)会沿继承链向上落到基类的定义;静态类型上只有纯虚声明(没有函数体)时,沿链向下落到实际的重写实现。多继承、隔代重写、跨文件派生都认。
- 拿不准时不装作确定 —— 同名类分布在不同命名空间、或条件编译的两个分支同时被索引时,几个可能的基类会一起作为候选给出,而不是替你猜一个。
跳转头文件
#include 行按 Ctrl/Cmd + 左键 或 F12,直接打开被包含的文件。
- 按编译器的顺序找 ——
"..." 先查当前文件所在目录(<...> 跳过这一步),再按 cindex.includePaths 的顺序逐个查;都落空时按文件名回工作区兜底,同名多份取「离引用处最近、路径更短」的那份。
- 能跳的会画下划线 —— 解析得到的路径下面有一条下划线,点击即打开,悬停显示目标路径;解析不出来的(
<stdio.h> 这类系统头、#include 宏)保持原样,不画也不跳。系统头想跳就把它加进 cindex.includePaths,例如 /usr/include。
调用关系
- 右键符号 →「CIndex: 显示调用者」,或调用关系视图,沿调用者一路向上展开;树节点单击即跳到对应代码行。
- 只做入向(谁调用我)。读代码要回答的是「这个函数被谁用到、改动会波及哪条链路」;出向(我调用了谁)顺着函数体往下看就有,再开一棵树只是重复信息。
当前文件
活动栏 CIndex 视图的「当前文件」页,两级分组:
- 文件内符号(默认展开)—— 当前文件里的全部符号按字母序平铺(不区分大小写、同名按行号)。每项左侧一个字母徽章标明类别:T 类型 / F 函数 / M 宏 / V 变量。单击跳转。
- 同目录文件(默认折叠)—— 当前文件所在目录下其它已索引的文件,按文件名升序,单击即打开。
切文件、保存后自动刷新。列表只包含已索引的文件 —— 被 cindex.skipDirs 排除的不会出现,不会有「列表里有、点进去跳不动」。
原生大纲
符号同时接入编辑器原生的「大纲」面板。树形层级与源码结构一致:结构体成员在结构体下、枚举成员在枚举下、平级函数并列。
由此免费得到一批能力——大纲面板自带的过滤框(边打边筛)、符号图标、Sort By(位置 / 名称 / 类别)、跟随光标、折叠全部,以及同样由它驱动的 Ctrl+Shift+O(转到编辑器中的符号)、面包屑导航与 Sticky Scroll(把当前作用域吸在编辑器顶部)。
与「当前文件」视图互补:大纲给层级与搜索,侧栏给字母序平铺与同目录文件。
若你同时装了其它 C/C++ 扩展,它们与 CIndex 会同时供大纲,面板里出现两套条目。关掉 cindex.outline.enabled 即可把大纲整块让回去。
全局符号查找
Ctrl+T(VS Code 自带的「转到工作区符号」)直接查 CIndex 索引 —— 不用学新按键,结果遵循 VS Code 原生符号的类别约定。要常驻搜索框就用下方 Global Symbols 视图。
- 与跳转定义同一份索引:查得到的都跳得过去,不会出现「列表里有、点进去跳不动」。
全局符号表
资源管理器那一栏的 Global Symbols 视图把整个索引的符号摊成一张可搜的表:每行「圆点 + 名字」加一行「类别 · 位置」,单击即跳。它回答的是「这个工程里都有什么符号」,与「当前文件」(我手上这个文件里有什么)、原生大纲(这个文件的层级)三者互补。
- 常驻搜索框 —— 输入子串即时过滤(不区分大小写),不用唤出任何查找控件。
- 输入总是跟手 —— 结果回来得再晚,也不会改写或打断你正在输入的内容。
- 四档类别筛选 —— All / Func / Type / Macro / Var,与「当前文件」视图的 T/F/M/V 徽章口径一致。
- 滚动续页 —— 滚到底自动续,状态行显示「N symbols · showing M」。
- 聚合条目显示出现次数,单击落到第一处(与「跳转定义」同口径)。
符号高亮
- 光标停在符号上按
F8,当前文件里所有同名位置一起高亮,再按一次取消;Shift + F8 强制取消。
- 注释与字符串里的同名文字不会被点亮。
- 不依赖索引 —— 还没同步、或者文件有未保存的改动都能正常工作。
- 深浅两套配色跟随编辑器主题自动切换;高亮位置同时标在滚动条上,长文件里一眼能看出别处还有哪几处。
其它
- 语义着色 —— 同步完成后,宏 / 类型 / 枚举成员按索引结果分色(可用
cindex.semanticHighlight 关闭);认不出的名字保持主题默认色。
- 索引范围由你决定 —— 索引的是已添加的文件夹;默认只跳过隐藏目录,其余一律进入索引。要排除第三方库 / 生成代码用
cindex.skipDirs,要强行纳入隐藏目录用 cindex.keepDirs(优先级 keep > skip > 默认);可写目录名(匹配任意层级),也可写相对索引根的路径后缀(带 / 时按路径匹配)。
- 编辑器外的改动自动跟进 —— 保存文件即时增量索引;切分支(
git checkout / git pull)、代码生成脚本、删除、重命名等发生在编辑器之外的变化也会自动跟进。只覆盖已添加的索引文件夹:工作区外的索引文件夹可能收不到较深层级的变化;索引尚未建立时不会触发 —— 首次索引仍由你手动发起。可用 cindex.autoSyncExternal 关掉。
- 同步全程有进度,随时可停 —— 状态栏持续显示已扫描规模与已耗时;长时间没有新进展会提示,最常见的原因是索引文件夹位于网络盘 / 共享盘。任意时刻点击状态栏即可取消,索引回到上一次完成的状态。
- 重启免重建 —— 索引完成后自动保存,重开编辑器直接恢复;索引格式升级时会提示重新同步一次。
- 后台索引时的机器保护 —— CPU 预算(
cindex.cpuBudget)、线程上限(cindex.maxThreads)、进程优先级(cindex.nice)、过载自动限速(cindex.throttle)四个开关,默认配置下后台索引不抢正常编辑的资源。
快速上手
- 打开 C/C++ 工程文件夹(
文件 → 打开文件夹)。
- 点状态栏的 CIndex 按钮,或命令面板执行「CIndex: 同步代码索引」。首次是全量,进度显示在状态栏。
Ctrl/Cmd + 点击 或 F12 跳转定义;右键符号 →「CIndex: 显示调用者」看调用链。
- 光标停在符号上按
F8 高亮同名位置。
- 之后正常写代码 —— 保存文件会自动增量索引;切分支、脚本生成代码、删除或重命名文件这类发生在编辑器之外的改动也会自动跟进,都不用手动同步。
工程大、首次同步慢的话,先用 cindex.skipDirs 排除掉第三方库和生成代码目录,索引量与耗时都会明显下降。
命令
| 命令 |
说明 |
| CIndex: 同步代码索引 |
同步已添加的文件夹(默认增量) |
| CIndex: 取消同步 |
中断正在进行的同步 |
| CIndex: 重建索引 |
清空后全量重建 |
| CIndex: 添加索引文件夹 / 移除索引文件夹 |
维护索引范围 |
| CIndex: 清空索引和缓存 |
内存与磁盘上的索引一起清掉 |
| CIndex: 显示索引状态 |
文件数 / 符号数 / 调用边数 / 内存占用 |
| CIndex: 显示调用者 |
光标处符号的调用关系 |
| CIndex: 刷新符号与同目录列表 |
手动刷新「当前文件」视图 |
| CIndex: 重新读取全局符号表 |
重新加载全局符号表(视图标题栏的刷新按钮) |
| CIndex: 显示全局符号表 |
把 Global Symbols 视图拉到眼前 |
| CIndex: 高亮光标处符号 / 取消符号高亮 |
高亮与取消(F8 / Shift+F8) |
| CIndex: 显示运行日志 |
打开「输出」面板的 CIndex 通道 |
快捷键
| 键位 |
命令 |
生效范围 |
F8 |
高亮光标处符号(再按一次取消) |
C/C++ 编辑器 |
Shift + F8 |
取消符号高亮 |
C/C++ 编辑器 |
编辑器默认把 F8 用作「转到下一个问题 / 错误」。本插件只在 C/C++ 编辑器里使用它;把设置 cindex.highlightKeybinding 关掉即可把 F8 还给编辑器,命令仍可从命令面板或右键菜单调用。换键位不必关掉它 —— 在「快捷键」里搜 CIndex 直接改,或在 keybindings.json 里为 cindex.highlightSymbol / cindex.clearHighlight 另绑,用户键位永远优先。
全库符号查找不占用任何快捷键:主力入口是编辑器自带的 Ctrl+T(「转到工作区符号」,已接入同一份索引);需要常驻搜索框时用资源管理器栏的 Global Symbols 视图。
设置
| 设置项 |
默认 |
说明 |
cindex.semanticHighlight |
true |
宏 / 类型 / 枚举成员的语义着色 |
cindex.highlightKeybinding |
true |
是否占用 F8 / Shift+F8 作为符号高亮快捷键 |
cindex.outline.enabled |
true |
是否把符号接入编辑器原生「大纲」面板(连带 Ctrl+Shift+O / 面包屑 / Sticky Scroll);与其它 C/C++ 扩展的符号重复时关掉 |
cindex.includePaths |
[] |
跳转 #include 时额外搜索的目录,支持 ${workspaceFolder} |
cindex.includeLinks |
true |
给能跳转的 #include 路径画下划线(关掉只是不画,F12 照常) |
cindex.autoSyncExternal |
true |
编辑器外的文件改动(切分支 / 代码生成 / 删除 / 重命名)自动增量同步 |
cindex.skipDirs |
[] |
追加跳过的目录(目录名,或相对索引根的路径后缀) |
cindex.keepDirs |
[] |
强制纳入的目录,优先级高于 skipDirs 与隐藏目录规则 |
cindex.maxThreads |
0 |
单引擎线程上限,0 = 按物理核数自动 |
cindex.cpuBudget |
0 |
整机索引进程共享的 CPU 预算(物理核),0 = 等于物理核数 |
cindex.nice |
10 |
索引进程的优先级下调幅度,0 关闭 |
cindex.throttle |
true |
机器过载时自动降低索引占用的 CPU |
cindex.logLevel |
minimal |
运行日志详略:minimal / verbose |
cindex.enginePath |
"" |
指定引擎可执行文件路径,留空用内置引擎 |
许可
MIT License