getblockheader该返回哪种格式？

同一个getblockheader调用可以服务两种完全不同的程序：一类需要区块头原始编码，自行计算哈希或验证协议；另一类需要高度、确认数、时间和链工作量，直接做索引与监控。verbose不是“输出更多日志”，而是在两个返回类型之间选择。

两种返回先在类型系统里分开

getblockheader必填blockhash；verbose默认为true，返回区块头信息对象。

verbose未传时默认为true，调用方得到对象；明确传false才得到十六进制字符串。生产客户端应为两种响应建立不同解析路径，缓存键也包含verbose。否则轻量对象和原始字节可能互相污染缓存，在边缘样本才暴露错误。

选择	返回	适合任务	客户端责任
false	序列化区块头的十六进制	哈希复算、编码测试、轻量传输	解码、字段切分、字节序处理
true	区块头JSON信息	链位置、监控、浏览器目录	处理条件字段与重组

输入永远是blockhash，不是高度。若上游只有高度，应先在同一节点取得哈希，并把高度到哈希的映射视为可能受重组影响的结果。

false只给区块头，不给交易

verbose=false返回序列化并进行十六进制编码的区块头数据，不包含完整交易列表。

原始返回承载版本、前一区块哈希、Merkle根、时间、难度目标和nonce等区块头内容，却不包含完整交易列表。Merkle根是对交易集合的承诺，不等于调用方已经获得或验证每笔交易。需要交易时应转向getblock相应verbosity，而不是从header结果猜测。

协议测试要保存原始十六进制和解码后字段，并用独立实现复算blockhash。测试向量应覆盖主链块、分叉块、不同版本位和高度边界。不要用浏览器页面重新复制字段替代原始RPC证据。

JSON对象里的字段要分四组读

JSON对象包含confirmations、height、version、merkleroot、time、mediantime、bits、difficulty和chainwork等字段。

身份组包括hash与height；链位置组包括confirmations、previousblockhash和nextblockhash；共识头字段包括version、merkleroot、time、mediantime、nonce与bits；累计比较组包括difficulty和chainwork。分组后，监控才不会把静态头内容与动态链位置混为一谈。

time来自区块头，mediantime是链上规则使用的中位时间口径，两者不能互换。difficulty便于展示，chainwork更适合比较链的累计工作；仍需使用同一网络和一致实现，不把不同链的数字直接排行。

confirmations=-1不是RPC失败

confirmations为-1表示区块不在主链；previousblockhash和nextblockhash仅在相应区块已知时出现。

当对象可返回但区块不在当前主链时，confirmations为-1。这通常意味着节点知道该区块头，却没有把它置于活动链。索引器应保留该blockhash和原始头数据，同时把链状态标为非活动，而不是删除历史或改写成查询失败。

previousblockhash在存在前驱时出现，nextblockhash只有节点能确定当前活动链中的下一块时才有意义。重组后next关系可能改变，所以它不是区块头本身的不可变组成。长期数据库应将父哈希作为头字段保存，将“活动链下一块”放在可更新的关系表。

一个重组安全的缓存方案

不可变层以network和blockhash为键，保存原始头、Merkle根、版本和工作量。可变层保存某次采样的height、confirmations、活动链标记和nextblockhash，并附节点、最佳块和时间。链头变化后只刷新可变层，避免把整个历史对象无差别重抓。

若应用按高度提供查询，响应中同时返回当时解析到的blockhash。后续同一高度出现不同哈希时，记录为重组事件，不能覆盖到无法审计。涉及资金确认的业务再按自己的确认门槛判断，而不是看到confirmations大于零就立即终结。

选择接口的最短规则

只需头字段且希望节点完成解释，用verbose=true；需要精确字节、复算哈希或跨实现比对，用false；需要交易对象，用getblock；需要监控分叉结构，再结合getchaintips。把这个接口边界写进SDK，能比运行时猜响应结构可靠得多。

先确定数据契约，再选择verbose

原始区块头适合协议级验证，JSON对象适合运维和索引。无论选哪一种，都用blockhash做稳定主键，把链位置视为会随重组变化的观测值。

资料台账与复核边界

Bitcoin Core 31 getblockheader：参数、两种返回和全部字段。
Bitcoin Core 31 getblock：完整区块对照。
Bitcoin developer guide block chain：区块头与交易承诺关系。

资料访问时间为2026-08-07。当前仍需按部署核验：链重组会改变confirmations和nextblockhash，长期存档必须以blockhash为主键并保留采样时点。

相关站内主题：getblock verbosity、waitfornewblock、getchaintips。本文用于技术教育与节点运维参考，不构成投资、收益或资产安全承诺。