每一次 The Graph 大版本升级都涉及协议层与工具链的多处变更。盲目升级容易踩坑，本文梳理最新版本的关键变化，帮助你做好准备。
协议层的关键变化
最新版本对 Indexer 选择机制做了优化，引入更细粒度的查询权重；同时 PoI 提交频次有所调整，对运营 Indexer 的团队需要重新计算成本。如果你的子图依赖某一 Indexer，建议提前沟通升级计划。详细参数表可参考 The Graph官方文档。
工具链 API 调整
graph-cli 与 graph-ts 中部分接口的命名做了调整，迁移时需要注意编译期的报错。常用模板可对照 The Graph代码示例 同步更新。Mapping 中的日志接口也做了精简，旧代码可能产生 deprecation 警告。
GraphQL 接口的兼容性
查询接口整体保持向后兼容，但部分新字段需要在 schema 中显式声明。前端调用方建议在升级后做一轮回归测试，确认所有查询行为一致。具体测试方案参考 The Graph进阶教程 中的回归章节。
升级前的准备
升级前请完成三件事：备份当前子图配置、记录上一版本的 IPFS 哈希、确认依赖库版本。任何一项遗漏都可能让回滚变得困难。把这些步骤写入团队 checklist，未来的每次升级都会更顺利。
升级中的注意事项
建议先在 staging 子图上跑一遍完整流程，包括同步、查询、监控。如果发现异常，按 The Graph常见错误 中的分类逐项排查。任何疑难问题都可以发到官方 Discord，社区响应速度普遍很快。
升级后的健康检查
升级完成后，至少观察 72 小时的关键指标：handler 错误率、同步落后区块数、查询响应时间。任意一项超过基线都需要立即定位。指标基线在 The Graph最佳实践 中有完整参考。
版本灰度策略
大型项目建议采用灰度策略：旧版本继续运行，新版本先承接 10% 流量，72 小时无异常后逐步切换。这样即使新版本出现问题，也能在最短时间内回滚。
版本升级既是风险，也是机会。准备充分、流程严谨，就能把每一次升级转化为产品体验的跃迁。