curl

NB

以下内容均以 113 年末更新至最新的 Windows Server 2022 所自带的简易版 curl 命令为基准，在诸 Linux 发行版上 curl 的功能只会更强而非更弱，因此亦应适用。

基本项

• -L 接受 URL 转址；
• -O 以连结中的名称（远端名称）下载至当前路径；
• -o "/designated/path/to/designated-filename.ext" 指定储存至在地的目的路径及目的档案名称；
• --output-dir 指定在地的目的路径；
• --create-dirs 在使用 -o 或 --output-dir, 或者在连用 -O 与 --output-dir 时，若指定的在地路径不存在，则需要加写此项来将其创建；
• -C - 恢复中断的传输（注意 C 后面还有一个横线，并与前面的 C 中间有一个空格！）；
• -Z 启用多执行绪并行执行（当连接中采用了 globbing 时会非常有用）；
• --parallel-max n 设定至多多少个执行绪并行执行，预设值为 50;
• -s 静默执行（萤幕上不显示任何字样）；
• -S 显示错误讯息，可与 -s 连用，即为：静默执行，但在出错时回报；
• -v 喧闹执行（萤幕上详细地显示与远端交互的每一步）；
• --connect-timeout n 设定逾时秒数；
• --max-time n 设定该次作业的以秒数计的总计时长上限；
• --rate n/u 设定每单位时间内进行多少次传输，其中 u 为时间单位，可为 s, m, 或 h, 如若设定 --rate 3/h, 则表示每小时传输 3 次；
• --retry n 设定该次传输作业中在遭遇失败时进行重试的次数（预设值为 0, 也即“失败不重试”）；
• --retry-max-time n 设定全部重试过程所最大可用的以秒数计的总时长上限；
• --retry-delay n 设定一个固定的失败与重试间的间隔秒数（预设值为从 1 秒起步，每次翻倍，直至 600 秒为限）；
• --retry-connrefused 设定为即便遭遇“连结被拒绝”也依然重试；以及
• --retry-all-errors 设定为无论遭遇何种错误反馈均依然重试。

作业 FTP

• -u username:password 在为作业 FTP 时指定使用者名称及密码。在仅使用登入资讯与一处 FTP 域名时，将得到该处 FTP 在使用该使用者登入后所得到的档案清单，加缀 --list-only 可获得只有名称没有其他细节的清单；
• -T "/local/path/to/the-file.ext" 指定要上载的在地档案；
• -Q "CMD dir-or-file" 执行指令，一般可见的指令有：
  • -Q "DELE filename.ext" 删除名为 filename.ext 的档案；
  • -Q "MKD dirname" 创建名为 dirname 的资料夹；相应地，亦有 -Q "RMD dirname" 用来删除名为 dirname 的空资料夹，但由于要删除的资料夹必须为空方可删除，且 -Q "DELE …" 的用法也有限，因此该指令其实用处不大；以及
  • -Q "RNFR old-filename.ext" -Q "RNTO new-filename.ext" 将原有的 old-filename.ext 档案重新命名为 new-filename.ext（注：无法透过此方法来移动档案）；
• 在作业 FTP 服务器一端时，不可使用 --create-dirs, 因为 --create-dirs 只适用于下载时对在地一方不存在的路径进行创建；若指定的上载路径不存在，则需要先——或许可能涉及逐级—— -Q "MKD …" 将指定的路径创建完毕，再行 -T "…" 传输；以及
• 在使用 -Q "CMD …" 执行指令的时候，切记档案或资料夹名称部分均不能有空格、不能使用万用字元或 globbing, 因此所能做到的事情极为有限，只能对单一具名对象进行处理。

URL Globbing

• curl 的 URL Globbing 可能看上去像是 RegEx 或是万用字元，但它两者都不是，切勿以 RegEx 的预设思想来写；
• curl 的 URL Globbing 总的来说有两种—— [x-y] 和 {a,b,c}, 其中前者表示范围，后者表示列举，以下为其用法的详细说明：
  • 与 RegEx 不同的是，[0-255] 表示从 0 到 255;
  • 如果在范围末尾加入冒号，写成形如 [0-255:5] 的样子，则表示从 0 开始计，每次增量为 5, 也即取 0, 5, 10, … , 255 这 52 个数；
  • 如果写成 [000-255] 的样子，则会自动补位；
  • 写成 [a-z:2] 也是可以的，这样便会取 a, c, e, … , y 这 13 个字母；
  • {a,b,c} 的用法为单纯的列举，因此没有什么好说的，不过 {a,b,c} 和 [x-y] 可以连用，甚至是多个连用，比如 {alauda,batiola,carruca}-[00-06:2] 就代表取 alauda-02, alauda-04, alauda-06, batiola-02, batiola-04, batiola-06, carruca-02, carruca-04, carruca-06 这九个值；以及
  • 如果连用更多，则被指涉到的档案就会非常多了，比如 s[01-06]e[01-09].{mp4,srt}, 则理论上可以表示从 s01e01.mp4 到 s06e09.srt 共计 108 个档案，如果其中有缺失的，则 curl 会自动跳过；
• 虽然叫做 ‘URL Globbing’, 但其实它是用在传输过程中的来源的地方的——这在下载过程中自然便是指的下载连结，因此这样讲没有问题，但是在上载过程中它是可以用在 -T 后面的 "/local/{aleph,bet,gimel}/file[01-10].{ex1,ex2}" 部分的；
• 在下载时，对于储存至在地的处所之路径与储存档案的名称，可以使用 #N 来援引在下载连结中透过 URL Globbing 表达的区块，此处的用法与使用 RegEx 进行取代作业的用法完全一致（只是表示第几个表达区块的引导字元不同），比如——
  • 若对 "https://example.com/{aleph,bet,gimel}/img[01-99].{jpg,png,webp}" 进行下载，则 -o 后面可以写成 "D:\Scatters\#1-#2.#3", 这样，curl 便会走访所有可能的组合，并将所有确实存在的连结所对应的档案都下载到 D:\Scatters\ 中，且储存下来的档案名称会形如 aleph-01.jpg, bet-23.png, 或 gimel-97.webp 的样子；
• 使用 -g 可在本次传输任务中关闭 URL Globbing 功能——这在当 URL 或者上载档案名称中包含 [, ], {, 和 } 字元而同时又并不需要使用 URL Globbing 时非常方便；或者
• 如果下载连结或上载档案名称中确有包含上述字元而同时又需要使用 URL Globbing 的话，那么需要将 [ 转写为 %5b, ] 转写为 %5d, { 转写为 %7b, } 转写为 %7d ——正常情况下，自浏览器拷贝出来的连结都应该是自动完成了这些转写的，因此主要适用场合为上载档案时档案名称中含有这些字元，但同时又需要使用 URL Globbing 时。