rclone lsd 命令完全指南：列出远端目录/容器/存储桶及其大小与对象数

rclone lsd 是 rclone 家族中专门用于只列出目录（不含文件） 的命令。它一次输出一行目录记录，包含该目录的总大小、修改时间、对象数量与目录名称，默认不递归、不输出文件，非常适合快速俯瞰一个远端存储里有哪些顶层目录或 Bucket。读完本文，你将掌握 lsd 的用法、输出字段解读、与 ls / lsl / lsf / lsjson 等兄弟命令的取舍，以及递归、过滤与底层调用链等进阶用法。

命令概述与定位

rclone lsd remote:path 的作用是把源路径下的目录/容器/存储桶列出到标准输出。它源自 ls（list）与 d（directories）的组合，其中文含义即"列出路径中的所有目录/容器/存储桶"。

在源码层面，命令由 cmd/lsd/lsd.go 实现，其 Cobra 命令定义为：

Use:   "lsd remote:path",
Short: `List all directories/containers/buckets in the path.`,

从命令行注册与标志绑定可以看到两个关键事实（cmd/lsd/lsd.go#L20-L24）：

• 命令属于 Filter 与 Listing 两个功能组（Annotations["groups"] = "Filter,Listing"），因此可以自由组合过滤与列表类全局参数；
• 唯一的本地标志是递归开关 -R/--recursive，其余选项全部继承自全局配置。

与 rclone ls 等命令一样，lsd 也遵守公共的过滤器语义。帮助文本中的公共段落集中定义在 cmd/ls/lshelp/lshelp.go，由 rclone ls、lsl、lsd、lsf、lsjson 等命令共享，这也是本文后续许多通用说明的直接出处。

输出格式详解

lsd 的每一行列出四个信息：目录总大小（未知则为 -1）、修改时间（未知则显示当前时间）、目录内对象数量（未知则为 -1）以及目录名称。

例如对 Swift 容器：

$ rclone lsd swift:
      494000 2018-04-26 08:43:20     10000 10000files
          65 2018-04-26 08:43:20         1 1File

第一列 494000 / 65 为该目录/容器内全部对象的大小合计（单位字节），第二列是修改时间，第三列 10000 / 1 是其中对象（文件）数量，最后一列 10000files / 1File 是容器名。

再如对 Google Drive 中的某个目录：

$ rclone lsd drive:test
          -1 2016-10-17 17:41:53        -1 1000files
          -1 2017-01-03 14:40:54        -1 2500files
          -1 2017-07-08 14:39:28        -1 4000files

这里的大小与对象数都是 -1，说明 Google Drive API 在列出目录时并不直接报告该目录的聚合大小与文件计数，rclone 无法获知便以 -1 占位，而不是去递归统计。这是由各后端的接口能力决定的：知道就显示真实值，不知道就显示 -1。

输出字段的代码级解读

上述列格式在 fs/operations/operations.go#L1047-L1057 的 ListDir 中生成：

SyncFprintf(w, "%s %13s %s %s\n",
    SizeStringField(dir.Size(), ci.HumanReadable, 12),
    dir.ModTime(ctx).Local().Format("2006-01-02 15:04:05"),
    CountStringField(dir.Items(), ci.HumanReadable, 9),
    dir.Remote())

可以从中确认几个细节：

• 大小字段默认以字节数右对齐展示（宽度 12）；对象数字段同样为定宽右对齐（宽度 9）。从 fs/operations/operations.go#L833-L864 的 SizeStringField / CountStringField 实现可见，若开启了 --human-readable，大小会换算为带 k/M/G 等后缀的可读形式并以 %9s / %8s 格式化，对象数则使用十进制计数后缀；
• 修改时间使用本地时区、格式固定为 2006-01-02 15:04:05；
• 如果目录的元数据缺失（大小、对象数不可知），后端会以 -1 填充；
• 修改时间未知时，展示的是由 --default-time 指定的默认时间（见下文"Listing 列表选项"）。

与 ls 系列命令的分工

rclone 提供了一整套"列表命令"以覆盖不同的输出诉求：

命令	输出内容	默认递归	设计取向
ls	仅列出对象的大小与路径	递归	人类可读
lsl	列出修改时间、大小与路径	递归	人类可读
lsd	仅列出目录	不递归	人类可读
lsf	以易解析格式列出对象与目录	不递归	人类与机器可读
lsjson	以 JSON 格式列出对象与目录	不递归	机器可读

需要注意两处反向默认值：

• ls 与 lsl 默认递归，如需只列当前层应使用 --max-depth 1 终止递归；
• lsd、lsf、lsjson 默认不递归，需加 -R 才进入递归模式。

用途选择建议：只想看目录名做脚本解析时用 rclone lsf --dirs-only；需要结构化数据交给程序处理时用 lsjson；而 lsd 的长处在于同时给出目录的规模（总大小、对象数、时间），用肉眼快速评估各目录的体积分布。

命令语法与自带选项

rclone lsd remote:path [flags]

lsd 自带（命令级）选项只有两个：

选项	含义
-h, --help	显示 lsd 帮助
-R, --recursive	递归进入子目录列出

-R 对应源码中名为 --recursive 的布尔开关（cmd/lsd/lsd.go#L23），在命令执行时它会把最大深度设为 0（即不限深度）后交给 ListDir（cmd/lsd/lsd.go#L61-L63）：

if recurse {
    ci.MaxDepth = 0
}
fsrc := cmd.NewFsSrc(args)
cmd.Run(false, false, command, func() error {
    return operations.ListDir(context.Background(), fsrc, os.Stdout)
})

而非递归模式下，深度则由 fs/operations/operations.go#L1037-L1044 的 ConfigMaxDepth 兜底为 1（仅当前层）。也就是说：-R 的本质就是把列举深度从 1 放宽到无限，同时按全局配置走 ListR/普通列举逻辑。

其余选项均来自全局 Flags。官方约定：命令页只列出命令自身 + 常见共享选项，完整的全局选项清单见 rclone flags 文档页。

共享选项：过滤（Filter Options）

lsd 属于 Filter 组，可以套用所有常规过滤规则来裁剪目录列表。共享的过滤选项如下：

选项	说明
--delete-excluded	同步时删除目标端被排除的文件（过滤配套项）
--exclude stringArray	排除匹配 pattern 的文件
--exclude-from stringArray	从文件读取排除模式（- 表示从标准输入读）
--exclude-if-present stringArray	若目录中存在该文件名则排除整个目录
--files-from stringArray	只处理从文件读入的源文件名列表（- 表示 stdin）
--files-from-raw stringArray	同 --files-from，但不对行做任何加工处理
--files-from0 stringArray	使用 NUL 作为分隔符读取源文件名列表
-f, --filter stringArray	添加一条文件过滤规则
--filter-from stringArray	从文件读取过滤 pattern（- 表示 stdin）
--hash-filter string	按 hash k/n 或随机 @/n 对文件名分区
--ignore-case	过滤时忽略大小写
--include stringArray	只包含匹配 pattern 的文件
--include-from stringArray	从文件读取包含 pattern（- 表示 stdin）
--max-age Duration	仅传输比该年龄更年轻（更新）的文件，单位 s 或后缀 ms|s|m|h|d|w|M|y（默认 off）
--max-depth int	限制递归深度（默认 -1，即不限）
--max-size SizeSuffix	只传输小于该大小的文件，单位 KiB 或后缀 B|K|M|G|T|P（默认 off）
--min-age Duration	仅传输比该年龄更老的文件（默认 off）
--min-size SizeSuffix	只传输大于该大小的文件（默认 off）
--metadata-exclude stringArray 及其 -from 变体	按元数据排除
--metadata-filter stringArray 及其 -from 变体	按元数据添加过滤规则
--metadata-include stringArray 及其 -from 变体	按元数据包含

这类过滤参数对 lsd 的典型价值在于"只见想看的部分"：例如用 --exclude-if-present 跳过含某标记文件的目录，或用 --min-size/--max-size 聚焦目标规模，从而把庞大存储的目录清单收敛到可读范围。

共享选项：列表（Listing Options）

针对目录列举本身，rclone 还提供两个共享列表选项：

选项	说明
--default-time Time	文件/目录修改时间未知时显示的时间（默认 2000-01-01T00:00:00Z）
--fast-list	若可用则使用递归 ListR 方法；占用更多内存但事务数更少

--default-time 直接决定了输出中"修改时间未知"时的展示值——因为每个后端能返回的目录元数据丰俭不一，无法返回 mtime 的目录会统一落到该默认时间。而 --fast-list 涉及列表的内部机制，见下一节。

关于 ListR 与 --fast-list

列表命令默认倾向于使用一种更占内存但事务更少的递归列举方法（ListR）。ListR 允许后端一次 API 请求拉回整棵子树，显著降低对远端存储的调用次数，代价是本地要缓冲更多条目。若某后端实现不可用或你希望禁用这一行为，可使用 --disable ListR 来抑制；--fast-list 则是与 ListR 同源的老选项名，语义为"如果可用就使用递归 List 方式"。

以 lsd 的命令分组（Filter,Listing）和默认执行路径看，普通模式（非 -R）下 ListDir 实际调用的是 fs/walk/walk.go 的 walk.ListR，它内部会结合 ConfigMaxDepth 决定是只列一层还是全树。关于该机制的更完整说明可查阅 --fast-list 的全局文档。

边界行为与注意事项

• 不存在的目录会报错，例外情况是那些"不允许存在空目录"的基于 Bucket 的远端，如 S3、Swift、GCS（Google Cloud Storage）等——对它们而言目录是隐式派生的，因此"列表不存在的桶"这类查询会得到错误而非空结果；
• 由于云对象存储普遍没有"文件夹"实体，lsd 输出的所谓目录在 S3/GCS/Swift 上即指存储桶/容器，命令描述中的 "directories/containers/buckets" 正说明了这一点；
• 大小与对象数不可知时输出 -1，这在解读输出时需与真实 0 区分：-1 表示"未统计"，0 才是"确实为空"；
• 想只拿目录名的纯净列表，请改用 rclone lsf --dirs-only，它比解析 lsd 的定宽列更省事且利于脚本处理。

实战示例速查

# 列出远端根下所有目录/容器（含大小、mtime、对象数）
rclone lsd myremote:

# 递归列出 myremote:docs 下全部层级的目录
rclone lsd myremote:docs -R

# 只看一级目录名（等价于 lsf 的 dirs-only 用法）
rclone lsf myremote: --dirs-only

# 套用过滤：排除名为 .ignore 的标记目录
rclone lsd myremote: --exclude-if-present .ignore

# 组合 max-depth 精确控制层级深度（-1 为不限）
rclone lsd myremote: --max-depth 2

# 若后端在递归列举时行为异常，可显式禁用 ListR
rclone lsd myremote: -R --disable ListR

底层实现要点速览

lsd 的执行链路非常短，便于阅读理解（全部位于仓库中）：

1. 入口命令：cmd/lsd/lsd.go 注册 lsd remote:path，-R 置 recurse 并把 ci.MaxDepth 置 0；
2. 源解析：cmd.NewFsSrc(args) 把 remote:path 解析为 fs.Fs 实例；
3. 列表核心：operations.ListDir（fs/operations/operations.go#L1047-L1057）经 walk.ListR 遍历，对每个 fs.Directory 输出格式化行；
4. 字段格式化：SizeStringField / CountStringField（fs/operations/operations.go#L833-L864）控制大小与对象数两列的宽度与可读性后缀；
5. 公共帮助：递归/兄弟命令/过滤等说明来自 cmd/ls/lshelp/lshelp.go，由各 list 命令共享，保证文档行为与代码一致。

需要指出的是，本文所描述的文档页由 make commanddocs 从 cmd/lsd/ 下的源码注释自动生成（文件头即声明 "autogenerated - DO NOT EDIT"），因此命令的帮助文本与真实行为天然同步，文档、命令行为与上述源码证据三者相互印证。

小结

rclone lsd 是把"目录视图"从远端存储中抽出来的高效工具：不递归、只列目录，一屏呈现每个目录的大小、修改时间与对象数。掌握它与 ls/lsl/lsf/lsjson 的差异（递归默认值、机器可读性）、-R 与 --max-depth 的深度控制、以及 Filter/Listing 两组共享选项，就足以在监控磁盘配额、盘点 Bucket 结构或撰写清理脚本时得心应手。