不用等到子命令才发现连错机：lncli 的十三个全局旗标逐项核对

lncli 每次敲下去，都要先回答三个问题：连哪台守护进程、拿什么凭证、以什么身份。这些决定由一组全局旗标做出——它们不属于任何子命令，写在命令前面或藏在环境变量里。多数故障（连不上、权限不够、操作错网络）都出在这一层，而不是子命令参数。本文全部以 LND v0.19.0-beta 源码为准，把 cmd/commands/main.go 里注册的这一整排旗标逐项过一遍。

定位类：rpcserver、lnddir、tlscertpath、chain、network

rpcserver 指定守护进程的 host:port，默认值 localhost 加 10009 端口（源码常量 defaultRPCHostPort 由 defaultRPCPort 拼出）。lnddir 是 lnd 的基目录，默认取操作系统的标准应用数据目录（源码用 btcutil.AppDataDir 生成），TLS 证书、macaroon、profile 文件都从它派生路径——tlscertpath 的默认值就是把默认目录拼上证书文件名。chain 默认 bitcoin，network 默认 mainnet，帮助文本列出的合法值包括 mainnet、testnet、testnet4、regtest、signet 与 simnet。这五个里有实操上最危险的一项：network 与 chain 决定去哪个目录找 macaroon，也决定付款落在哪条链。拿主网凭证去戳 testnet 的 lnd，典型症状是”证书或权限文件找不到”，根因却是这两个旗标。

鉴权类：no-macaroons、macaroonpath、macaroontimeout、macaroonip

除非 lnd 端配置了禁用 macaroon，每次 RPC 都要出示令牌文件。macaroonpath 手工指定文件路径，no-macaroons 直接不带凭证——后者只在 lnd 明确关闭鉴权时可用，开了鉴权还加这个旗标，换来的是权限拒绝而不是免密通过。剩下两个属于请求期加固：macaroontimeout 默认 60，给每次请求附带的凭证加一个 60 秒有效窗，用途写在使用说明里——防重放；macaroonip 一旦设置，把凭证锁到指定来源地址。两者共同点是不改变令牌文件本身，而是在每次调用时附加约束，适合对脚本化调用做最小权限收紧。timeout 默认值只有一分钟这件事本身就是一种提醒：跨时区服务器跑定时任务，先确认时钟同步，否则凭证会因时间漂移在途中过期。

通路类：socksproxy 与 insecure

socksproxy 让 lncli 到 lnd 的 gRPC 连接整体走一个 SOCKS 代理——把命令行工具桥进 Tor 环境、或从隧道另一头操作远程节点时用它。insecure 是隐藏旗标（源码里 Hidden），含义是”不带 TLS 认证地连接”，帮助文本直白到近乎警告：Connect to the rpc server without TLS authentication。它与 lnd 服务端的 --no-rest-tls 是两回事，且只该出现在本机回环或可信隧道里；公网 RPC 用 insecure 裸连，凭证等于明文寄送。

档案类：profile、macfromjar、metadata

profile 把上面那一整组连接参数收进一个命名书签，按名字取用；帮助文本还给了一个反向技巧：当存在默认档案时，把它设成空字符串可以暂时禁用档案读取，回到命令行与本文件的取值。macfromjar 依附档案系统，指定从档案的 macaroon 集合里取哪一个，仅限定义了档案时可用。metadata 支持重复传，以 key:value 形式给每次请求的上下文附加键值对，用途是给服务端或中间件带自定义元数据。三个旗标构成一条清晰的演进线：一次性调用用旗标，多节点复用收进 profile，需要多套凭证在同一档案间切换时上 macfromjar。

优先级：谁说了算

同一参数在命令行、环境变量、档案三处都有值时，取用顺序有明确规则：显式命令行旗标优先，其次环境变量（每个定位与鉴权类旗标都绑了以 LNCLI 打头的对应环境变量名，如 LNCLI_RPCSERVER、LNCLI_LNDDIR、LNCLI_NETWORK），再其次是档案里的存值。这解释了两类”配置文件不生效”的假象：shell 里残留的导出变量悄悄覆盖了你以为在用的默认值；或档案存在时，你以为改了旗标，实际读的仍是档案副本。诊断姿势很简单——lncli profile list 看有没有档案接管，env | grep LNCLI 看有没有变量在背景里说话，两者都排除后，命令行旗标才是你真正设下的那个值。

风险提示：本文为命令行工具机制科普，旗标与默认值以 LND 当前版本源码为准，可能随版本调整；凭证与连接配置涉及资产控制权，请自行验证适用性；不构成投资建议。

一组可背下来的常用组合

远程节点带自定义目录：lncli --rpcserver=地址:10009 --tlscertpath=路径 --macaroonpath=路径 getinfo；同机多实例用网络旗标切换：lncli --network=testnet walletbalance；脚本里免拼装路径走环境变量：导出 LNCLI_LNDDIR 指向目标实例目录后所有命令自动继承。三个组合覆盖了日常运维的绝大多数现场，记住旗标之间的派生关系——目录决定证书与令牌的默认位置、网络决定目录下的子路径——比背整张参数表更耐用。