不装钱包软件，用 curl 跟节点说话：JSON-RPC 报文与 cookie 鉴权 图 1
不装钱包软件，用 curl 跟节点说话：JSON-RPC 报文与 cookie 鉴权 · 图 1

一次裸调用长什么样

比特币节点的 RPC 服务就是一个 HTTP 服务器。官方文档给出的最小例子是：用 curl 带用户凭据，向本地 RPC 端口发一段 JSON，方法名写进 body。例如以 --user alice 交互式输入口令，body 里放 {"jsonrpc": "2.0", "id": "0", "method": "getblockcount", "params": []}，目标是 localhost:38332/（示例端口，以实际配置为准）。bitcoin-cli 做的事情与此几乎完全相同，只是替你把报文拼好。理解这一层的价值在于：任何工具——脚本、监控、别的语言——只要能发 HTTP 请求，就能操作节点，RPC 不是一个私有协议，就是 JSON 加 HTTP。

不装钱包软件，用 curl 跟节点说话：JSON-RPC 报文与 cookie 鉴权 图 2
不装钱包软件，用 curl 跟节点说话：JSON-RPC 报文与 cookie 鉴权 · 图 2

两种常见形态。一种是固定的用户名口令（-rpcuser 配 -rpcpassword），写在配置里；另一种是 cookie：节点启动时在数据目录里生成一个 .cookie 文件，内容形如”用户名:随机口令”，同机的客户端工具读它自动完成认证，省得明文口令躺在配置文件里。bitcoin-cli 在同机场景默认就用这条路。用 curl 手动访问时，可以用 --user 加 cookie 文件里的用户名，口令部分交给交互式输入；--netrc 等方式也能免把口令敲进命令行历史。无论哪种，记住 RPC 默认没有传输层加密，这也是接口文档和发行说明反复强调不要把 RPC 直接暴露到公网的原因——暴露不等于加了用户名就安全，口令会在网络上明文过一遍。

多钱包：路径决定给谁打电话

节点可以同时加载多个钱包。不带路径的根路径请求永远可以处理非钱包类方法；钱包类请求只有在恰好只加载了一个钱包时才能由根路径处理。一旦加载了两个或更多钱包，钱包类请求必须走 /wallet/钱包名 路径，例如示例中的 localhost:38332/wallet/desc-wallet（bitcoin-cli -rpcwallet=名字 用的就是这条路径）。非钱包类方法（查链、查内存池、网络类）与路径无关，写在哪儿都一样。多钱包环境里忘带钱包路径，是典型的”明明余额不对”的来源。

v28 之后：报文里多了一个标记

从 28.0 起，RPC 服务识别 JSON-RPC 2.0：请求里带 "jsonrpc": "2.0" 字段时按 2.0 规范应答，不带时按 1.1 风格应答，两者兼容不冲突，但客户端若同时解析两种格式要按文档对齐。这是”报文兼容性”层面最值得一提的变化。

四类报错的最短定位

401：认证失败，查 cookie 路径、用户名口令和 RPC 端口是否指向同一数据目录。404：路径错了，多半是钱包名写错或方法不该走 /wallet/ 路径。连接被拒：RPC 没开、端口不对或只监听本机而你在远程。方法未找到：方法名拼错、版本太老（RPC 有生命周期）、或它根本不是这个服务类别的方法。把这四类当成排查树，比”换个写法再试试”高效得多。

本文不构成投资建议。

从报错样本反推配置错误

实际运维里，curl 直连最常见的三种失败分别是：HTTP 401、连接被拒、方法报错。401 几乎总是凭据与数据目录不匹配——机器上有多个节点实例时，cookie 文件是各目录独立的，拿 A 目录的 cookie 调 B 目录的端口必然失败；先确认端口再确认凭据，顺序反了会绕远路。连接被拒通常是 RPC 根本没启用（有些发行默认只为 GUI 内部启用本机 RPC），或者你从远程机器访问一个只绑定本机的端口——这不是 bug，是默认安全姿态。方法类报错里最有信息量的是”方法不存在”：它要么拼写错了，要么你的节点版本没有这个方法，要么它属于钱包类别而你没有带钱包路径。三类错误对应三类修法（换 cookie、开 RPC 或走隧道、核对版本与路径），先把错误原文完整读一遍再动手，比凭印象试运气快得多。顺带一条经验：把常用调用存成带注释的脚本仓库，每次变参只改数组参数，可以避免大量手滑引号问题。