调试是子图开发中最容易被低估的能力。一旦上线，问题往往不是「跑不起来」，而是「跑得起来但数据不对」。本文围绕 The Graph 的三层调试视角，介绍每一层的核心方法与工具。
本地 graph-node 的日志解读
在本地启动 graph-node 后，最先要看的就是终端输出。Mapping 函数的 log.info 与 log.error 会原样输出到控制台。建议在每个 handler 入口处打印事件哈希与区块号，遇到偏差时一眼就能锁定位置。对应日志级别配置可对照 The Graph入门指南 中的环境变量章节，开启 DEBUG 模式后细节更丰富。
Matchstick 单元测试
Matchstick 把 AssemblyScript 测试体验拉到了接近主流编程语言的水平。可以在测试用例中模拟事件、断言实体字段、清理状态。它的最大价值在于：让你在不部署的情况下完成 80% 以上的逻辑验证。常用断言写法可结合 The Graph代码示例 中的模板代码，复制即可上手。
托管节点的状态接口
部署到托管服务后，可以通过 indexingStatus 查询当前同步进度、错误位置以及最新 handler。把它接到监控系统里，能在第一时间感知到子图卡住或者错误退避。常见的卡同步表现与解决方法在 The Graph常见错误 中有完整对照。
PostgreSQL 执行计划分析
The Graph 底层存储仍是 PostgreSQL。查询变慢时，可以通过 graph indexer-cli 拿到底层 SQL 并执行 EXPLAIN ANALYZE。重点关注是否走了索引、是否触发 Seq Scan，以及 derivedFrom 关联的 join 顺序。必要时为高频字段补充索引，整体响应时间通常能下降数倍。
链上事件回放
对于历史数据怀疑遗漏的场景，可以用 graph-cli 的 replay 命令，把指定区间内的事件重新喂给 Mapping。这种方式在追溯审计或处理合约升级历史时极为有用。把回放结果与原始链上事件对比，就能验证逻辑是否完备。
性能剖析与持续改进
调试不仅是排错，更是性能改进。建议每两周做一次 indexing latency 与查询 P99 的复盘，并与 The Graph最佳实践 中的指标基线对比，持续打磨。把方法沉淀下来，你的团队就能在子图领域形成可观的工程优势。