lncli buildroute 手工指定路线：把每一跳写死再预演一笔闪电付款

一、queryroutes 与 buildroute 的分工

LND 默认自己找路：queryroutes 在图谱上算出一条可行路径给你过目，sendtomessage、sendpayment 则让路由算法全程自动。buildroute 把选择权整个交还给你：调用方逐个写出中间节点的公钥，LND 不再搜索，只负责把这条人肉指定的路径翻译成一份能直接执行的 HopHints——每一跳的费用、时间锁、通道 ID 按图谱里的最新报价填好。它挂在路由子服务下，lncli buildroute 是同名入口。本文按 LND v0.19.0-beta 的接口定义核对。

二、请求字段的读法

amt_msat 是付款金额，注释特别提醒：填零会退到”最小可路由金额”，测试时想清金额不要偷懒。final_cltv_delta 是最后一跳的时间锁增量，不填就用节点的默认值——注释专门写了一段警告：必须按发票实际要求的增量来填，填小了，最后一跳会直接拒绝这笔 HTLC。outgoing_chan_id 锁定第一跳走哪条通道，填零表示”第一跳随意”。hop_pubkeys 是中间节点公钥列表，不含你自己，也不含收款人。payment_addr 是最后一个关键字段：注释写明，只要目标发票声明了 payment secret，这个字段就必须提供，否则洋葱包在最后一跳解不出来。

响应就是一份 Route 对象，和 queryroutes 返回的结构相同，可以直接喂给按路由支付的接口逐字节执行。

三、它验什么、不验什么

buildroute 做的校验是图谱层面的：路径上每一跳的通道是否存在、报价如何、按你给的金额和时间锁算出总费用与 CLTV 总量。它不做的事同样清楚：不试探通道此刻的真实余额，不确认对端节点是否在线，不保证这笔钱真能穿过去——那是 Mission Control 概率数据负责的事。换句话说，一条”图谱上可行”的路径可能因为某条通道此刻一侧余额不足而失败，也可能因为对端宕机而卡在某一跳。用它做付款预演时，看到的是一笔费用与锁的账本，不是成功率的承诺。

四、典型用法

第一类是排障：同一笔金额分别 buildroute 两条候选路径，比较费用与时间锁差异，确认路由算法选贵了还是选错了；如果图谱报价可疑，再配合 graph 检查对应边的 fee 字段。第二类是合规或策略路由：某些场景要求付款避开特定节点，自动算法没有这种过滤概念，手工列节点是唯一直接的写法。第三类是自定义 HTLC 流程：走 hold invoice、需要精确控制时间锁链条的应用，会先 buildroute 拿死每一跳参数，再决定何时真正发起。

五、边界与自查

第一，报价来自本地图谱，可能滞后于全网；buildroute 算出的费用与真实执行时收到的报价不一致并不罕见，付款前的 queryroutes 复核仍有价值。第二，hop_pubkeys 的先后顺序就是资金流经顺序，写反了不会报”路径不通”，只会算出一条驴唇不对马嘴的 Route，执行时才失败，脚本里应当从图谱数据反向生成这份列表而不是手敲。第三，它不产生任何链上或通道动作，纯本地计算，可以放心反复调用，不会留下付款记录。

六、与 queryroutes 的配合姿势

实战里两条命令常搭配使用：先跑 queryroutes 看算法眼中的最优解，再用 buildroute 把手工路径跑出来，两个 Route 对象的费用、时间锁、跳数并排一比，路由偏好的来源立刻明朗——算法是避开了某条贵边，还是押注某条历史成功率高的通道。给自动化应用写『强制走某路径』逻辑时，把 buildroute 的输出先缓存再交给按路由支付的接口，中途图谱刷新不会改变已算好的金额；真正发起支付前再校验一次金额与发票未被改签。测试网里还有一层用途：教学与文档演示需要一条确定路径时，buildroute 让示例每次跑出来完全一致，不受网络报价波动影响，这比看运气等算法挑哪条的演示稳定得多。

风险提示：手工路由的付款失败率高于自动路由，大额操作请先小额试路。本文只做机制说明，不构成投资建议。