做过 The Graph 子图的开发者都有一段被报错刷屏的回忆。无论是币安智能链上的 DEX 数据，还是以太坊主网上的借贷协议，错误类型其实集中在十类之内。本文把它们一次性梳理清楚，给出排查与修复的最短路径。
起始区块与事件未触发
最常见的「子图同步完成却查不到数据」问题，多半是起始区块设得太晚，或者合约 ABI 与链上字节码不一致。建议先用区块浏览器找到合约部署区块，再向前留 500 个区块作为安全余量。若仍异常，对照 The Graph入门指南 中的 ABI 校验流程逐字段比对。
Mapping 函数中的类型转换
AssemblyScript 对 BigInt 与 BigDecimal 的隐式转换控制极严。常见的「Cannot convert」一类报错，几乎都源于直接把 i32 与 BigInt 混用。统一使用 BigInt.fromI32 与 BigDecimal.fromString 转换，可以消除九成此类错误。复杂运算示例见 The Graph代码示例，里面给出了价格、利率、流动性等典型公式。
实体保存顺序
子图实体之间存在外键关系时，必须先 save 父实体再 save 子实体，否则会在 indexer 端报「Entity not found」。对于一次事件需要更新多张表的场景，建议显式排序，并在末尾做一次完整性校验。
subgraph.yaml 配置错位
network、address、abi 三个字段任何一项填错都会导致全量失败。币安智能链常被写成 bsc 或 binance-smart-chain，最新规范是 bsc，旧版本是 bnb。每次升级 graph-cli 后都建议用 codegen 重新生成代码再部署。
部署阶段的网络问题
国内开发者常遇到 graph deploy 卡住或者 IPFS 上传失败的问题。临时方案是切换到自建 IPFS 节点，或者使用全球加速节点。结合 The Graph部署教程 中的代理配置可大幅提高成功率。
查询性能退化
子图运行一段时间后，如果查询变慢，多半是某张表索引缺失或者 derivedFrom 关系滥用。可以使用 graph indexer-cli 查看慢查询日志，结合 PostgreSQL 的 EXPLAIN 分析具体瓶颈。深入的优化技巧详见 The Graph进阶教程。
避开这些常见错误，子图开发就能从「天天救火」转向「按计划交付」。把它们整理进团队的 onboarding 手册，新人也能少踩很多冤枉路。