Tree-sitter 入门：3 分钟跑通你的第一个增量解析器

【免费下载链接】tree-sitterAn incremental parsing system for programming tools项目地址: https://gitcode.com/gh_mirrors/tr/tree-sitter

做 Tree-sitter 入门之前，先聊一个你肯定遇过的问题：敲下一个字符，编辑器却要等 500ms 才把高亮刷出来。

"卡"的根源是解析方式。老思路是每次改动都从文件头扫到尾，文件越大越慢。Tree-sitter 换了个活法：把源码组织成语法树，只重算受影响的一小块，其余直接沿用——这就是 Tree-sitter 增量解析原理的精髓。

一句话定位：Tree-sitter 是"解析器生成器 + 增量解析库"，能把任意语言的源码变成一棵语法树，并在编辑时高效更新它。三个卖点先记住：

• 快：设计目标就是"每次按键都解析一遍也不心疼"；
• 稳：源码有语法错误也不崩，解析器会绕过错误区域继续产出可用的树；
• 零依赖：运行库是纯 C 写的，嵌进任何应用都行。

三分钟跑通最小可运行示例

准备两样东西：Tree-sitter 本体，加上一个现成的语言包（本文以 JSON 为例，即tree-sitter-json）。核心代码不到 20 行，存成test-json-parser.c：

#include <stdio.h> #include <string.h> #include <tree_sitter/api.h> const TSLanguage *tree_sitter_json(void); // 由 JSON 语言包提供 int main() { TSParser *parser = ts_parser_new(); // 创建解析器（"引擎"） ts_parser_set_language(parser, tree_sitter_json()); // 插上 JSON 语言包 const char *source = "[1, null]"; // 把源码字符串解析成语法树，第二参 NULL 表示没有旧树可复用 TSTree *tree = ts_parser_parse_string(parser, NULL, source, strlen(source)); char *out = ts_node_string(ts_tree_root_node(tree)); // 取根节点，整棵树转字符串 printf("语法树: %s\n", out); free(out); // 三样内存都要还：字符串、树、解析器 ts_tree_delete(tree); ts_parser_delete(parser); return 0; }

先别管编译，下一节的心智地图会把这段代码里的每个对象讲透。

四个核心对象的心智地图

与其背定义，不如把它想成一套车载导航 🧭 四个对象排成一条流水线：

TSLanguage（图例）→ TSParser（引擎）→ TSTree（路网）→ TSNode（路口）

• 图例 TSLanguage：规定每个语法符号怎么读，由tree-sitter generate从语法文件编译而来，你基本不用手写；
• 引擎 TSParser：长驻的有状态对象，插上哪份图例，就能解析哪种语言；
• 路网 TSTree：整个文件的结构一网打尽，它自己可以被编辑，是增量重算的入口；
• 路口 TSNode：树上每个节点都带字节偏移与行列坐标，还知道自己的父节点、兄弟节点在哪。

协作流程一句话：引擎按图例把源码铺成路网；你改了一段路，就把旧路网连同编辑信息交回引擎，它只重算断掉的那一段，其余路段原封不动。旧树别扔——它正是下次省时间的本钱，记住这一点，就抓住了 Tree-sitter 语法树使用的核心。

编译链接一步到位 + 新手最容易踩的 3 个坑

编译要凑齐三种"食材"：头文件目录、语言包的parser.c、运行时库。⚠️ 一样都不能少：

# 第一步：在 tree-sitter 目录里生成静态库 libtree-sitter.a make # 第二步：头文件 + 语法 parser.c + 运行时库，三样齐活 clang -I tree-sitter/lib/include \ test-json-parser.c tree-sitter-json/src/parser.c \ tree-sitter/libtree-sitter.a -o json-parser ./json-parser

跑通后你会看到一行 S 表达式：(document (array (number) (null)))。

新手最容易踩的 3 个坑：

1. 漏掉语言包的 parser.c：链接时报undefined reference to tree_sitter_json——语言代码不在运行时库里，每种语言都是独立包；
2. 动态链接后找不到库：改用-ltree-sitter编译没问题，运行却提示找不到libtree-sitter.so，建议检查LD_LIBRARY_PATH；
3. 忘记还内存：ts_node_string返回的字符串需要free，树和解析器也要 delete，长驻进程里这就是慢性泄漏。

生产环境再注意两点：解析前建议检查ts_parser_set_language的返回值，为 false 时多半是语法包与运行时的 ABI 版本不匹配；处理大文件时，可以改用ts_parser_parse配自定义TSInput回调，从自己的数据结构里按偏移取文本。更多细节见官方文档。

下一步做什么？两个具体方向

1. 写一门自己的语言：读一读语法 DSL 指南，用grammar.js描述规则，执行tree-sitter generate生成parser.c——Tree-sitter 就成了你手里的解析器工厂；
2. 基于语法树做代码智能：先遍历命名节点实现语法高亮，再用 query 做符号导航与引用索引。到这里，这篇 Tree-sitter 解析器教程的入门部分就完整交付了，剩下的全是造轮子的乐趣。

【免费下载链接】tree-sitterAn incremental parsing system for programming tools项目地址: https://gitcode.com/gh_mirrors/tr/tree-sitter