区块高度和区块哈希是链上寻址的两把钥匙，而比特币核心里负责把高度翻译成哈希的 getblockhash，是很多人第一次写对账脚本时撞墙的地方。命令只吃一个参数，返回一个哈希，看上去没有可出错的空间，实际有三道边界决定了脚本的健壮性。本文以比特币核心 v31.0 源码为准。
命令的准确语义
getblockhash 的接口定义只有一行说明：返回当前最好链上给定高度处的区块哈希。参数就是高度整数。实现层面，它先在活动链上按高度取区块索引，命中后返回该索引的区块哈希。这里有个容易被忽略的前提：它查的是当前活动链，不是全部已知链。如果那条高度所在的分叉已经被移出主链，这条命令不会去找旧分叉上的邻居。
越界行为的准确答案
v31.0 源码里对参数做了两处约束：高度为负，或者大于本节点当前链尖高度，都会抛出 invalid parameter 类错误，错误文本是 Block height out of range。注意这里没有商量的余地——不是返回空串，不是返回零哈希，而是直接报错。脚本层面最常见的一类事故，就是拿一个尚未同步到的高度去查询，被这行代码弹回。所以同步中调用任何历史查询接口，都要把越界错误当作可预期的分支处理，而不是当成故障。
与 getblockheader 的接力
用高度定位到哈希之后，下一步通常是 getblockheader：按哈希取区块头，verbosity 默认打开，返回里同时有高度、确认数、时间戳与中位时间、bits、target、difficulty、链累计工作量，以及前块哈希与后块哈希。这一对组合是遍历区块头的标准姿势：按高度步进取哈希，再按哈希取头，靠 previousblockhash 与 nextblockhash 校验链条没有因为重组错位。裁剪节点同样能走这条路，因为区块头信息不占裁剪预算。
遍历时的三个实践要点
第一，缓存链尖。开始前先记下当前高度，遍历的上限用这个快照值，避免边扫边长导致边界漂移。第二，把重组当作背景事件。遍历中途节点发生重组时，同一高度可能对应新的哈希，长程遍历完成后应对收尾一小段重新核对，或者按前块哈希连续性做一次全链自检。第三，别用它做时间换算。高度不等于时间，平均出块时间是十分钟量级的统计概念，用高度反推日期属于误用，需要精确时间时用区块头里的时间戳与中位时间字段。
一条最小可用流程
先 getblockcount 拿链尖，再在循环里 getblockhash 步进，每若干个区块抽查一次 getblockheader 的前后哈希衔接。这个骨架在同步完整、未裁剪、只读的节点上都成立，也是把这条命令用对的最低成本路径。
与其他寻址方式的关系
除了按高度取哈希，节点还提供按哈希取整块、按哈希取头部、按区块统计等多条寻址入口。区别只在返回的信息量：只要坐标信息就用 getblockheader，要交易明细才升级到 getblock 的高 verbosity 档。把这两级阶梯记住，既省流量也避免在裁剪节点上问了不该问的问题。
处理越界报错的最小代码习惯
写批量脚本时把越界错误单列一个分支：捕获错误文本里的高度越界关键字，把它解释为节点尚未同步到此高度，然后等待同步追进后重试；与其他错误码区分开，能省掉大半夜误报的故障单。同理，链尖也可能因为重组变小，长任务里隔一阵重新读一次当前高度，比开场读一次用到底更稳。
风险提示：本文只解释节点接口行为，不构成任何投资建议；示例为通用流程，请以所用软件版本的实际返回为准。
发表评论
还没有评论，来说两句吧。
评论区为展示样式，提交不会被处理。