开发者指南

cURL 下载文件:保存、断点续传与校验

使用 cURL 的 -o 和 -O 保存文件,区分 HTTP 错误与有效内容,管理临时文件,在服务器支持时续传,并校验完整文件。

下载示例文件

用 curl --output filename URL 指定本地文件名,也可以用 curl --remote-name URL 从 URL 路径取得文件名。可靠的下载还要检查 HTTP 结果,将未完成的内容放在临时文件中,并验证收到的文件。

本教程使用虚构 CSV 和一个 131,072 字节的二进制文件。本地服务也提供 404 和中途断开的响应,便于观察下载失败时的实际输出。

流程概览

用 -o 或 -O 选择本地文件名

解压示例包,进入 examples 目录并在一个终端启动服务。

python3 demo_server.py

另开终端,创建输出目录并保存 CSV。

mkdir -p downloads
curl --fail --show-error --silent \
  --output downloads/catalog.csv \
  'http://127.0.0.1:8772/files/catalog.csv'

简写为 curl -fSs -o downloads/catalog.csv URL。-o 接收本地路径。先创建父目录,需要保留历史文件时请使用新文件名。

需要沿用 URL 路径中的名称时,进入目标目录并使用 -O。

cd downloads
curl --fail --show-error --remote-name \
  'http://127.0.0.1:8772/files/archive.bin'
cd ..

-O 从 URL 取得 archive.bin。需要读取响应的 Content-Disposition 文件名时,请了解单独的 -J 选项。如果来源提供的名字不合适,可指定本地名称。更多命名规则见 curl 选项手册。

将临时文件与最终文件分开

连接建立后,服务器仍可能返回 404、登录页或 HTML 错误。--fail 将 HTTP 400 及以上错误视为失败。收到 HTTP 200 时也应核对文件内容。

以 CSV 为例,将响应头和正文分别保存,正文使用临时文件名。

curl --fail --show-error --silent \
  --dump-header downloads/catalog.headers \
  --output downloads/catalog.part \
  --write-out 'HTTP %{http_code}; bytes %{size_download}\n' \
  'http://127.0.0.1:8772/files/catalog.csv'

本地服务返回 HTTP 200 和 Content-Type: text/csv; charset=utf-8。确认文件列名为 id,name,amount,currency,并且包含三条商品记录后,再改成最终名称。其他格式可用对应的解析器或文件签名校验。

确认 curl 成功退出且内容检查通过后,再重命名 .part 文件。

结果

处理方式

HTTP 200,内容符合预期

完成文件检查后使用最终名称

使用 --fail 时收到 HTTP 404

将命令视为失败

HTTP 200,但正文是登录页或错误页

修正访问权限或 URL 后再试

传输在声明长度之前结束

根据需求决定保留或删除部分文件

收到重定向

核对目标地址或指定适当的重定向策略

已知需要跟随重定向时,可以使用 --location,并用 --max-redirs 限制跳转次数。检查最终地址和文件内容。

资源未变化时续传部分文件

续传从本地文件的现有偏移量之后追加字节。服务端需要支持范围请求,而且现有字节应属于同一份资源。同名文件也可能已经更新。

以下示例从已下载的本地二进制创建一个可控的部分文件。完整文件为 131,072 字节,先保留开头的 32,768 字节。

head -c 32768 downloads/archive.bin > downloads/archive.part
curl --fail --show-error --silent \
  --continue-at - \
  --dump-header downloads/resume.headers \
  --output downloads/archive.part \
  'http://127.0.0.1:8772/files/archive.bin'

--continue-at 后的 - 表示按本地文件长度确定偏移量。虚构服务器返回 HTTP 206 及以下响应头。

Content-Range: bytes 32768-131071/131072

完整文件含 131,072 字节,SHA-256 如下。

59f410ae5e17962412e2aed4f815918f634932f2abf084f00bb638c4db017850

macOS 可运行 shasum -a 256 downloads/archive.part,GNU coreutils 环境可用 sha256sum。对于远程文件,有发布者提供的可信校验值时应与其比对。

服务端拒绝续传或资源已变化时,用新的临时文件重新下载。续传机制见 curl 续传指南。

32,768 字节的部分文件通过 HTTP 206 续传,最终得到 131,072 字节的完整文件。
示例从偏移量 32,768 开始续传,收到剩余 98,304 字节。

明确处理下载失败

本地 /files/missing.bin 返回 404。启用 --fail 后,curl 退出码为 22。/files/truncated.bin 声明 1,000 字节却只发送 10 字节,curl 退出码为 18。磁盘上存在文件时,也要检查传输状态。

从头下载时,curl 7.83.0 及以上支持 --remove-on-error,可在出错后移除输出。需要续传时使用 --continue-at 并保留部分文件,两项选项互斥。

如果通过 MIYAIP 代理访问远程资源,按连接指南配置实际端点和鉴权。仍需独立验证下载内容。本文的 HTTP 地址是虚构回环服务,真实远程 Basic 凭据应通过 HTTPS 发送。

常见问题

curl 为什么把文件内容输出到终端?

curl 默认输出到终端。用 -o 指定本地文件名,或用 -O 采用 URL 路径中的名字。读取响应头中的文件名需要单独配置。

-L 能保证下载成功吗?

-L 会跟随重定向。还应检查最终 HTTP 状态、内容是否符合预期及文件完整性。

Windows PowerShell 能执行这些命令吗?

使用 curl.exe 明确调用 curl。示例中的续行、head 和校验命令使用 POSIX shell 语法,请按当前 shell 使用相应命令,保留 curl 参数。

继续使用 MIYAIP