比特币 getnewaddress 领地址的真相：从密钥池发号到标签归组逐项核对

比特币节点 RPC 里，getnewaddress 是使用频率最高的钱包命令之一：要收款了，先领一个新地址。它的名字里有 new，实际行为却不是现场”造”一枚新密钥，理解这一点才算真正会用。本文按 Bitcoin Core v31.0 源码核对它的取号逻辑、参数语义与自动化里的坑。

一、新地址从哪里领

源码里的执行链是先检查钱包有没有可用密钥，再从描述符对应的密钥派生区间里取下一个未用位置。所谓 new，指的是这个地址在钱包的账本上此前没有被标记为已使用。这意味着密钥早已按分层结构批量派生好，命令只是”发号”；如果发号机用尽，它直接报错提示密钥池耗尽，而不是无限生成——这时需要 keypoolrefill 扩充窗口。助记词恢复钱包后”明明有收款却看不见”的经典事故，根源也是发号进度对不上：链上的钱落在第 2050 个位置，钱包只扫到第 2000 个。

二、label 参数是账本分组键

第一个字符串参数是标签，会写进钱包地址簿。此后凡转入该地址的款项，在按标签统计的收入报表里都归到这个名下。标签不存在会自动创建，不必事先登记；同一标签可以挂多个地址，适合”一个业务、多张收款码”的场景；空串是默认标签，从不写标签时所有地址都归到它。两个边界要记牢：标签纯本地不上链，换机器不带、对方看不见；标签金额与总余额天然可能对不上，因为没打标签的旧地址不参与其中，这是口径差异不是丢账。

三、address_type 只影响这一次

第二个参数指定地址格式（传统、嵌套隔离见证、原生隔离见证、Taproot 等枚举值），不写时跟随启动配置 addresstype 的默认。它的正确用法是临时兼容：对方老系统只认旧格式时，单独生成一枚旧式地址救急，而不动全局默认。传了不认识的字符串会得到参数错误；想永久改默认，应该改配置重启节点，而不是在脚本里每条命令都带参数——那样生成的地址类型和你钱包的长期策略脱节，日后自己都对不上账。

四、锁定状态与观察钱包

加密钱包锁着时能不能领地址，取决于密钥池里还有没有存货：池子没耗尽时命令照常发号；一旦需要补充派生而钱包又处于锁定，日志会记一条”锁钱包补充密钥池失败”，命令报出密钥池耗尽、提示先解锁再 keypoolrefill。所以严谨说法是：领已有号不要求解锁，造新号要求。纯观察性质的空钱包调用它会报”没有可用密钥”：观察钱包的正确姿势是用导入描述符的方式批量生成监控地址，指望 getnewaddress 是不行的。多钱包节点记得带 rpcwallet 指明目标，否则默认钱包领出来的地址与你计划的收款账户毫无关系。

五、自动化的三个提醒

订单系统”每单一个地址”的常见模式里：把标签（比如订单号）与返回的地址一并落进你自己的库，否则事后只能拿地址反查；命令幂等性不存在，调两次给两个地址，不要拿它当”查询当前收款地址”用；每次领号都推进发号进度，测试脚本循环领地址会把区间很快耗光，触发密钥池耗尽报错——测试用 regtest 或加大窗口。

风险提示：地址与密钥的生成、保管涉及资产安全，恢复钱包后请先核对地址区间再确认收款完整性；本文不构成投资建议。