rclone ls 命令完全指南云存储对象列表的输出格式、递归规则与过滤实战【免费下载链接】rclonersync 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/rclonerclone 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仅目录含大小、修改时间、对象数人类可读否需-Rlsf对象与目录格式易于解析人类与机器可读否需-Rlsjson对象与目录JSON 格式机器可读否需-R选型要点需要在终端里快速看一眼文件与大小用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 fubuwiclsd只看目录lsd列出目录及其总大小、修改时间、目录内对象数与目录名例如$ rclone lsd swift: 494000 2018-04-26 08:43:20 10000 10000files 65 2018-04-26 08:43:20 1 1Filelsd不递归在 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自行排序处理。大小列宽为 9SizeStringField(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支持任何过滤选项用于控制哪些对象会被列出。这些标志在列出目录时生效完整清单如下标志类型说明--delete-excluded布尔删除目标端被同步排除的文件属于 sync 类语义的标志与过滤规则一起提供--excludestringArray排除匹配模式的文件可多次指定--exclude-fromstringArray从文件读取排除模式用-表示从标准输入读取--exclude-if-presentstringArray若目录中存在该文件名则排除该目录--files-fromstringArray从文件读取源文件名清单用-表示标准输入--files-from-rawstringArray从文件读取源文件名清单不做任何行处理用-表示标准输入--files-from0stringArray从文件读取源文件名清单以 NUL 字符作为分隔符用-表示标准输入-f, --filterstringArray添加一条文件过滤规则支持/-前缀--filter-fromstringArray从文件读取过滤模式用-表示标准输入--hash-filterstring按哈希 k/n 或随机 /n 对文件名分区--ignore-case布尔过滤时忽略大小写--includestringArray包含匹配模式的文件可多次指定--include-fromstringArray从文件读取包含模式用-表示标准输入--max-ageDuration只处理比该时间更年轻的文件单位 s 或后缀 ms|s|m|h|d|w|M|y默认 off--max-depthint若设置则限制递归深度默认 -1表示不限制--max-sizeSizeSuffix只处理比该大小更小的文件单位 KiB 或后缀 B|K|M|G|T|P默认 off--metadata-excludestringArray排除元数据匹配模式的对象--metadata-exclude-fromstringArray从文件读取元数据排除模式用-表示标准输入--metadata-filterstringArray添加元数据过滤规则--metadata-filter-fromstringArray从文件读取元数据过滤模式用-表示标准输入--metadata-includestringArray包含元数据匹配模式的对象--metadata-include-fromstringArray从文件读取元数据包含模式用-表示标准输入--min-ageDuration只处理比该时间更老的文件单位同--max-age默认 off--min-sizeSizeSuffix只处理比该大小更大的文件单位同--max-size默认 off注意三个细节其一--max-depth默认值为-1而ls/lsl默认无限递归二者叠加意味着如果不显式传--max-depth 1ls会遍历全部层级其二--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.txtListing 选项Listing Options除了过滤标志ls还接受以下与列目录方式直接相关的选项标志类型说明--default-timeTime当文件/目录的修改时间未知时用于显示的时间默认2000-01-01T00:00:00Z--fast-list布尔若可用则使用递归列表消耗更多内存但事务更少--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 cant 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。【免费下载链接】rclonersync 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考