企业官网建设流程全解析

rclone ls 命令完全指南：云存储对象列表的输出格式、递归规则与过滤实战

【免费下载链接】rclone"rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files项目地址: https://gitcode.com/GitHub_Trending/rc/rclone

rclone ls是 rclone 中最常用的对象列举命令之一，它以人类可读的格式将远端路径下的所有对象（文件）及其字节大小输出到标准输出，默认递归遍历全部子目录。本文以 rclone 官方命令文档 docs/content/commands/rclone_ls.md 为骨架，结合 rclone 的 ls 命令实现 与 operations 列表核心代码，系统讲解rclone ls的语法、输出格式、递归行为、与其姊妹命令lsl/lsd/lsf/lsjson的取舍，以及过滤选项的完整用法，帮助你在选型与脚本化时准确驾驭 rclone 的列表命令家族。

rclone ls 能做什么：语法与基础输出

rclone ls的作用是"列出路径中的对象，附带大小与路径"。它的调用语法为：

rclone ls remote:path [flags]

执行后，rclone 会把源路径中的对象以人类可读格式（字节大小 + 对象路径）打印到标准输出，且默认递归遍历所有层级。文档中的典型示例如下：

$ rclone ls swift:bucket 60295 bevajer5jef 90613 canole 94467 diwogej7 37600 fubuwic

从输出可以看出每一行只有两列：左侧是文件大小（单位字节），右侧是相对路径（即对象相对于remote:根的 remote 路径）。注意该输出不包含目录条目，只列出对象；若需要目录信息，应使用rclone lsd。

从命令自身语法看，ls只接受一个位置参数。在 cmd/ls/ls.go 中，命令定义通过cmd.CheckArgs(1, 1, command, args)强制要求恰好传入一个remote:path参数，随后调用cmd.NewFsSrc(args)解析参数得到一个源文件系统fsrc，最终执行的核心逻辑是：

cmd.Run(false, false, command, func() error { return operations.List(context.Background(), fsrc, os.Stdout) })

也就是说，rclone ls本身只是一个薄壳，真正的列表逻辑全部位于 fs/operations/operations.go 的List函数中（见下文"从源码看输出格式"一节）。

五个列表命令：ls、lsl、lsd、lsf、lsjson 如何选择

rclone 提供了一族密切相关的列表命令，它们共享同一份帮助文本（定义于 cmd/ls/lshelp/lshelp.go，并被ls、lsl、lsd、lsf、lsjson共同引用）：

选型要点：

• 需要在终端里快速"看一眼"文件与大小，用ls；
• 需要确认修改时间是否一致、排查同步差异，用lsl；
• 只想了解目录结构而忽略内部文件，用lsd；
• 要把结果喂给 awk、Python 或 Excel 做进一步处理，优先lsf或lsjson；
• 需要把列表结果直接作为结构化数据交给程序消费（如 Web API、脚本 JSON 解析），用lsjson。

lsl：追加修改时间列

lsl与ls的唯一差别是在大小后追加了本地时区的修改时间（精确到纳秒）。其官方示例如下：

$ rclone lsl swift:bucket 60295 2016-06-25 18:55:41.062626927 bevajer5jef 90613 2016-06-25 18:55:43.302607074 canole 94467 2016-06-25 18:55:43.046609333 diwogej7 37600 2016-06-25 18:55:40.814629136 fubuwic

lsd：只看目录

lsd列出目录及其总大小、修改时间、目录内对象数与目录名，例如：

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

lsd不递归；在 cmd/lsd/lsd.go 中通过--recursive/-R布尔标志控制：一旦指定-R，就会把配置中的MaxDepth设为0（表示不限制深度）后再执行operations.ListDir。如果只需要目录名，官方文档建议使用rclone lsf --dirs-only。

递归行为的差异（关键易错点）

• ls与lsl默认递归，若只想要顶层内容，用--max-depth 1终止递归；
• lsd、lsf、lsjson默认不递归，需要递归时显式加-R。

这一差异常导致使用者困惑：在容量很大的远端桶上直接执行rclone ls remote:会把全部分层文件一次性打出来。想快速浏览顶层结构时，最稳妥的组合是rclone lsf remote: --max-depth 1或直接rclone lsd remote:。

ListR 与 --fast-list：列表命令的"省事务"模式

列表命令默认倾向于使用递归列目录（ListR）方法：它比逐目录分页列举消耗更多内存，但所需的网络事务更少，因此在大目录场景下速度更快。官方文档的原文提示为：

List commands prefer a recursive method that uses more memory but fewer transactions by default.

如果某个远端在 ListR 下表现不佳（例如实现不完整、超时或返回错误），可以通过--disable ListR禁用该行为，回退到逐目录列举。相关概念--fast-list会指示 rclone "如果后端支持递归列表则使用它（代价是更多内存、更少事务）"，完整的全局说明见仓库根目录的 MANUAL.md（全局标志部分）。需要特别指出：ListR是后端能力特性，只有实现了该特性的存储后端才会真正走 ListR 路径，其余后端会自动退化，这正是--disable ListR作为逃生阀存在的原因。

从源码看输出格式与精度

ls的输出并非随手打印，而是经过严格格式化。看 fs/operations/operations.go 中List的实现：

// Shows size and path - obeys includes and excludes. // // Lists in parallel which may get them out of order func List(ctx context.Context, f fs.Fs, w io.Writer) error { ci := fs.GetConfig(ctx) return ListFn(ctx, f, func(o fs.Object) { SyncFprintf(w, "%s %s\n", SizeStringField(o.Size(), ci.HumanReadable, 9), o.Remote()) }) }

几个值得注意的实现细节：

• 并行列举：注释明确写着 "Lists in parallel which may get them out of order"，即ls通过并发列举对象并回调输出，因此结果的顺序并不保证。若需要稳定排序，应配合sort管道或改用lsjson/lsf自行排序处理。
• 大小列宽为 9：SizeStringField(o.Size(), ci.HumanReadable, 9)表示原始字节数按固定宽度 9 右对齐打印（人类可读模式宽度写死，最长值约为"999.999Ei"的 9 字符）。这解释了示例中"60295"前面的对齐空格。
• --human-readable选项：ci.HumanReadable控制是否把字节数格式化为带二进制后缀（如Ki/Mi）的形式，例如rclone ls --human-readable remote:会输出58.8Ki这样的数值，这一选项在列宽逻辑上也有所区隔。
• 路径列：o.Remote()给出对象相对根目录的路径（相对路径使用/分隔），是解析输出时的第二字段。
• 相邻的ListLong（对应lsl）同样以 9 字符宽打印大小，随后是modTime.Local().Format("2006-01-02 15:04:05.000000000")格式的本地修改时间（Go 参考时间格式，精确到纳秒），最后是路径，并且对每个对象会计入 "listing" 的 checking transfer 统计。
• ListDir（对应lsd）的目录行则使用宽度 12 的大小列，并追加CountStringField的对象数统计。

过滤选项（Filter Options）完整参考

ls支持任何过滤选项，用于控制"哪些对象会被列出"。这些标志在列出目录时生效，完整清单如下：

注意三个细节：其一，--max-depth默认值为-1，而ls/lsl默认"无限递归"，二者叠加意味着如果不显式传--max-depth 1，ls会遍历全部层级；其二，--min-size/--max-size的默认单位是 KiB（即 1024 字节的二进制倍数），也可以用后缀B|K|M|G|T|P精确指定；其三，--max-age/--min-age默认单位是秒，可接ms|s|m|h|d|w|M|y后缀（其中M指月、y指年）。这些年龄/大小过滤与ls的列表调用共享底层过滤管线，因此可以放心组合。

实用的过滤示例：

# 只列出当前层级（不递归） rclone ls remote:path --max-depth 1 # 只列出大于 100MiB 的对象 rclone ls remote:path --min-size 100M # 排除所有 .tmp 文件与 archive 目录 rclone ls remote:path --exclude "*.tmp" --exclude "archive/**" # 只列出最近 7 天内修改的对象 rclone ls remote:path --max-age 7d # 从文件读取排除规则 rclone ls remote:path --exclude-from exclude.txt

Listing 选项（Listing Options）

除了过滤标志，ls还接受以下与列目录方式直接相关的选项：

• --default-time主要用于那些不保存精确修改时间的后端：当lsl、lsd或lsjson需要输出 modtime 而远端没有该信息时，rclone 用此值兜底。
• --fast-list是全局标志--fast-list的命令行显式开关，与上文 ListR 机制对应。

ls命令自身没有专属选项，只有通用帮助标志-h, --help：

-h, --help help for ls

除本页列出的 Filter/Listing 组标志外，其余通用选项（如连接并发数、超时、带宽限制、日志级别等）均属于全局标志，由 rclone 的 全局标志文档 统一说明。

不存在的目录与"无法有空目录"的远端

rclone ls列出一个不存在的目录会产生错误，但有一类例外：对于本身无法存在空目录的远端（例如基于 bucket 的 s3、swift、gcs 等对象存储），列一个"逻辑上不存在"的目录并不会报错——因为在这些存储中目录并非真实实体，它只是对象键名的前缀。官方原文为：

Listing a nonexistent directory will produce an error except for remotes which can't have empty directories (e.g. s3, swift, or gcs - the bucket-based remotes).

这一行为在脚本中要尤其注意：对本地盘（local）、Drive 等有真实目录概念的后端，路径拼错会立刻得到 error；而对 s3 这类存储，rclone ls s3:bucket/some/missing/prefix往往只是返回空结果而非报错，判断"目录是否存在"应改用rclone lsd或检查返回的对象数。

实战组合：把 ls 用到自动化流程中

rclone ls输出结构简单（<size> <path>），非常适合在 shell 管道中二次加工。配合上述选项可以构造出很多实用场景：

# 统计远端某个前缀下的对象总数与总字节数 rclone ls remote:path | awk '{n++; s+=$1} END {print "files:", n, "bytes:", s}' # 找出大于 1GiB 的对象清单 rclone ls remote:path --min-size 1G # 仅输出 2023 年 1 月之后修改过的文件路径（交给 xargs 处理） rclone lsl remote:path --min-age 2023-01-01 | awk '{print $3}' # 输出到文件后再人工核对 rclone ls remote:path --max-depth 2 > listing.txt

在需要程序化、稳定、可排序且字段完备的输出时，请直接转向lsjson（每行一个 JSON 对象、字段含 name/path/size/modTime/IsDir 等）或lsf（可用--format自定义字段顺序、--separator自定义分隔符、--csv输出 CSV），而不是在ls的文本上做脆弱的列解析——这正是 rclone 官方把两者定位为"机器可读"的原因。

小结：何时用 ls，何时换命令

回到本文开头的问题：当你想以人类可读的大小 + 路径格式、默认递归地快速盘点云端某个前缀下有哪些对象时，rclone ls就是那个最直接的工具。使用时要记住三件事：它默认全量递归（用--max-depth 1收敛）；它只输出对象不含目录（目录请交给lsd）；它不保证输出顺序且不含修改时间（按时间排查请用lsl，面向解析请用lsf/lsjson）。在此基础上叠加本文完整列出的过滤选项与递归控制手段，你就可以精准、高效地驾驭 rclone 的整个列表命令家族。

想继续深入：可阅读本命令的文档源文件 docs/content/commands/rclone_ls.md、共享帮助文本实现 cmd/ls/lshelp/lshelp.go，以及列表核心逻辑 fs/operations/operations.go 中List/ListLong/ListDir三个函数（fs/operations/operations.go#L871-L893 与 fs/operations/operations.go#L1047-L1057）；姊妹命令的实现位于 cmd/lsl/lsl.go、cmd/lsd/lsd.go。

【免费下载链接】rclone"rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files项目地址: https://gitcode.com/GitHub_Trending/rc/rclone