如何使用 curl 下载文件

Q: curl -o 和 curl -O 有什么区别？

-o filename 将下载保存到您指定的确切文件名。-O 从 URL 中提取文件名并使用该名称。需要自定义名称或路径时用 -o；远程文件名合适时用 -O。

Q: 如何使用 curl 恢复部分下载的文件？

使用 curl -C - -o filename URL。-C - 选项检测已有文件大小并发送 Range 头部仅请求剩余字节。服务器必须支持范围请求才能生效。

Q: 如何限制 curl 的下载速度？

使用 --limit-rate 加数值和后缀：curl --limit-rate 500k -o file URL 将速度限制在 500 KB/s。后缀：k（KB/s）、M（MB/s）、G（GB/s）。

Q: curl 能同时下载多个文件吗？

可以。使用多个 -O 选项：curl -O URL1 -O URL2 -O URL3。curl 按顺序下载。如需并行下载，将 URL 列表管道传输到 xargs -P 4 -I {} curl -O {}。

Q: 如何下载需要认证的文件？

HTTP Basic Auth：curl -u user:pass -o file URL。Bearer token：curl -H "Authorization: Bearer TOKEN" -o file URL。头部中的 API key：curl -H "X-API-Key: KEY" -o file URL。

Q: 如何使用 curl 从 FTP 服务器下载文件？

使用 curl -u user:pass -o localfile ftp://host/path/file。curl 原生支持 FTP、FTPS（FTP over TLS）和 SFTP（SSH FTP）。匿名 FTP 可省略 -u。

Q: 如何可靠地下载大文件？

组合 -C -（失败时恢复）、--retry 5（自动重试）、--retry-delay 10 和 -L（跟随重定向）：curl -C - --retry 5 --retry-delay 10 -L -o file URL。这会自动处理网络中断。

Q: 下载时如何显示进度条？

使用 curl -# -o file URL 显示简单进度条。默认 curl 输出已显示传输速度、百分比和预计时间。脚本中使用 -s 隐藏所有输出。

Q: curl 能指定下载目录吗？

curl 7.73+ 可使用 --output-dir /path/to/dir 与 -O 组合。旧版本使用 -o /path/to/dir/filename 指定完整路径。如果目录不存在，添加 --create-dirs。

curl 是通过 HTTP、HTTPS、FTP 及数十种其他协议下载文件的最通用命令行工具之一。无论是将单个 API 响应保存到文件，还是在 shell 脚本中自动化批量下载，curl 都有对应的选项。本指南涵盖所有与下载相关的选项——从使用 -o 和 -O 进行基本文件保存，到使用 -C - 恢复中断的传输、使用 --limit-rate 限制带宽以及显示进度条。每个选项都包含清晰的说明、常见用法模式和可直接复制的示例。

下载选项快速参考

选项	说明
-o	将输出写入指定文件而非 stdout
-O	将输出写入与远程文件同名的文件
-L	自动跟随 HTTP 3xx 重定向
-C -	继续/恢复之前的文件传输
--limit-rate	将传输速度限制在指定速率
--max-filesize	拒绝下载超过指定大小的文件
-J	使用 Content-Disposition 头部来命名文件
-#	以简单进度条显示传输进度
-u	提供用户名:密码进行服务器认证
--retry	遇到临时错误时重试传输（次数）
--retry-delay	两次重试之间等待的秒数
-T	将本地文件上传到 URL（默认使用 PUT）
--create-dirs	保存输出时根据需要创建本地目录
-s	隐藏进度指示器和错误消息
--output-dir	将输出文件保存到指定目录（curl 7.73+）

将输出写入指定文件而非 stdout

将输出写入与远程文件同名的文件

自动跟随 HTTP 3xx 重定向

继续/恢复之前的文件传输

将传输速度限制在指定速率

拒绝下载超过指定大小的文件

使用 Content-Disposition 头部来命名文件

以简单进度条显示传输进度

-u

提供用户名:密码进行服务器认证

--retry

遇到临时错误时重试传输（次数）

--retry-delay

两次重试之间等待的秒数

-T

将本地文件上传到 URL（默认使用 PUT）

--create-dirs

保存输出时根据需要创建本地目录

-s

隐藏进度指示器和错误消息

--output-dir

将输出文件保存到指定目录（curl 7.73+）

curl -o：保存到指定文件名

功能说明: -o（或 --output）选项告诉 curl 将响应体保存到您指定的文件中。如果不使用该选项，curl 会将响应输出到 stdout（您的终端）。您可以使用任何文件名和路径——curl 会创建文件或覆盖已有文件。
常见用法: 当您需要精确控制文件名或保存到特定目录时使用 -o。它适用于任何协议——HTTP、HTTPS、FTP、SFTP 等。可与 -L 组合处理重定向，与 -s 组合在脚本中静默运行。

$ curl -o report.pdf https://example.com/files/report.pdf

curl -O：使用远程文件名保存

功能说明: -O（或 --remote-name）选项使用从 URL 中提取的文件名保存下载的文件。例如，如果 URL 以 /data.csv 结尾，curl 会在当前目录创建名为 data.csv 的文件。
常见用法: 当远程文件名有意义且您不需要重命名时使用 -O。您可以传递多个 -O 选项在一条命令中下载多个文件。注意：如果 URL 不包含文件名（例如以 / 结尾），curl 将失败——请改用 -o。

$ curl -O https://example.com/files/data.csv

curl -L：跟随重定向

功能说明: -L（或 --location）选项使 curl 自动跟随 HTTP 重定向——301（永久移动）、302（临时移动）、307 和 308。不使用 -L 时，curl 返回重定向响应本身而非实际内容。
常见用法: 大多数下载 URL 至少重定向一次（例如从 HTTP 到 HTTPS，或从短链接到实际文件）。下载文件时务必将 -L 与 -o 或 -O 组合使用。默认情况下 curl 最多跟随 50 次重定向；可通过 --max-redirs 修改。

$ curl -L -o latest.tar.gz https://github.com/user/repo/releases/latest/download/app.tar.gz

curl -C -：恢复中断的下载

功能说明: -C -（或 --continue-at -）选项告诉 curl 自动检测已有不完整文件的大小，并从断点处恢复下载。服务器必须支持 HTTP Range 头部才能使此功能生效。
常见用法: 如果大文件下载因网络问题或超时而中断，只需添加 -C - 重新运行相同命令。curl 将发送 Range: bytes=OFFSET- 头部，仅下载剩余数据。这对于不稳定连接上的大文件至关重要。

$ curl -C - -o largefile.zip https://cdn.example.com/largefile.zip

curl --limit-rate：限制下载速度

功能说明: --limit-rate 选项将下载（和上传）速度限制在指定速率。它接受后缀：k 或 K 表示千字节/秒，m 或 M 表示兆字节/秒，g 或 G 表示吉字节/秒。
常见用法: 下载大文件时使用 --limit-rate 避免占满带宽，尤其在共享连接上。它也适用于测试应用程序如何处理慢速响应。

$ curl --limit-rate 1M -o bigfile.iso https://mirror.example.com/bigfile.iso

curl --max-filesize：文件过大时中止

功能说明: --max-filesize 选项告诉 curl 在预期文件大小（来自 Content-Length 头部）超过指定限制时中止传输。大小可以使用 k、M、G 等后缀。
常见用法: 在脚本中使用以防止意外的大文件下载占用磁盘空间。请注意并非所有服务器都发送 Content-Length——在这种情况下，curl 无法执行此限制，下载将正常进行。

$ curl --max-filesize 100M -o update.bin https://example.com/update.bin

curl -J：使用服务器建议的文件名

功能说明: -J（或 --remote-header-name）选项告诉 curl 使用服务器 Content-Disposition 头部中指定的文件名，而非从 URL 中提取。这在返回有意义文件名的下载 API 中很常见。
常见用法: 始终将 -J 与 -O 组合使用。当 URL 是 API 端点（如 /export?format=csv）但服务器在头部中返回正确文件名时很有用。安全注意：文件名由服务器控制，因此仅与受信任的服务器一起使用。

$ curl -L -O -J https://example.com/api/export?format=csv

curl -#：显示进度条

功能说明: -#（或 --progress-bar）选项将默认的详细进度指示器替换为简单的 ### 进度条。这在交互使用时更易阅读。
常见用法: 交互式下载时如果需要简洁的进度指示器，使用 -#。脚本中建议使用 -s（静默）或默认进度指示器。默认 curl 输出已显示速度、百分比、剩余时间和总大小。

$ curl -# -o archive.tar.gz https://example.com/archive.tar.gz

其他下载选项

选项	说明
-u	提供用户名:密码进行服务器认证
--retry	遇到临时错误时重试传输（次数）
--retry-delay	两次重试之间等待的秒数
-T	将本地文件上传到 URL（默认使用 PUT）
--create-dirs	保存输出时根据需要创建本地目录
-s	隐藏进度指示器和错误消息
--output-dir	将输出文件保存到指定目录（curl 7.73+）

-u

提供用户名:密码进行服务器认证

--retry

遇到临时错误时重试传输（次数）

--retry-delay

两次重试之间等待的秒数

-T

将本地文件上传到 URL（默认使用 PUT）

--create-dirs

保存输出时根据需要创建本地目录

-s

隐藏进度指示器和错误消息

--output-dir

将输出文件保存到指定目录（curl 7.73+）

实际下载场景

这些示例组合多个选项来处理日常开发和脚本编写中常见的下载任务。

同时下载多个文件

使用多个 -O 选项在一条命令中下载多个文件。curl 按顺序处理它们。如需并行下载，使用 xargs 或 GNU parallel。

$ curl -O https://example.com/file1.txt -O https://example.com/file2.txt -O https://example.com/file3.txt

从 FTP 服务器下载

curl 原生支持 FTP、FTPS 和 SFTP。添加 -u user:password 进行认证访问。使用 -O 保留远程文件名。

$ curl -u user:pass -o backup.sql ftp://ftp.example.com/db/backup.sql

带认证下载

使用 -u user:pass 进行 Basic Auth，或使用 -H 传递 Bearer token 或 API key。与 -L 和 -o 组合实现完整下载。

$ curl -H "Authorization: Bearer eyJhbGciOi..." -L -o data.json https://api.example.com/export

带恢复和重试的可靠下载

组合 -C -（恢复）、--retry（失败时自动重试）和 -L（跟随重定向），实现能经受网络中断的稳健下载。

$ curl -C - --retry 5 --retry-delay 10 -L -o largefile.zip https://cdn.example.com/largefile.zip

curl 下载常见问题

curl -o 和 curl -O 有什么区别？

-o filename 将下载保存到您指定的确切文件名。-O 从 URL 中提取文件名并使用该名称。需要自定义名称或路径时用 -o；远程文件名合适时用 -O。

为什么 curl 下载了空文件或 HTML 文件而不是实际文件？

URL 可能返回了 HTTP 重定向（301 或 302）。默认情况下，curl 保存的是重定向响应本身——而非最终内容。添加 -L 自动跟随重定向：curl -L -o file URL。

如何使用 curl 恢复部分下载的文件？

使用 curl -C - -o filename URL。-C - 选项检测已有文件大小并发送 Range 头部仅请求剩余字节。服务器必须支持范围请求才能生效。

如何限制 curl 的下载速度？

使用 --limit-rate 加数值和后缀：curl --limit-rate 500k -o file URL 将速度限制在 500 KB/s。后缀：k（KB/s）、M（MB/s）、G（GB/s）。

curl 能同时下载多个文件吗？

可以。使用多个 -O 选项：curl -O URL1 -O URL2 -O URL3。curl 按顺序下载。如需并行下载，将 URL 列表管道传输到 xargs -P 4 -I {} curl -O {}。

如何下载需要认证的文件？

HTTP Basic Auth：curl -u user:pass -o file URL。Bearer token：curl -H "Authorization: Bearer TOKEN" -o file URL。头部中的 API key：curl -H "X-API-Key: KEY" -o file URL。

如何使用 curl 从 FTP 服务器下载文件？

使用 curl -u user:pass -o localfile ftp://host/path/file。curl 原生支持 FTP、FTPS（FTP over TLS）和 SFTP（SSH FTP）。匿名 FTP 可省略 -u。

如何可靠地下载大文件？

组合 -C -（失败时恢复）、--retry 5（自动重试）、--retry-delay 10 和 -L（跟随重定向）：curl -C - --retry 5 --retry-delay 10 -L -o file URL。这会自动处理网络中断。

下载时如何显示进度条？

使用 curl -# -o file URL 显示简单进度条。默认 curl 输出已显示传输速度、百分比和预计时间。脚本中使用 -s 隐藏所有输出。

curl 能指定下载目录吗？

curl 7.73+ 可使用 --output-dir /path/to/dir 与 -O 组合。旧版本使用 -o /path/to/dir/filename 指定完整路径。如果目录不存在，添加 --create-dirs。

下载文件应该用 curl 还是 wget？

两者都很出色。wget 更适合递归网站镜像，内置重试逻辑。curl 支持 25+ 种协议（不仅是 HTTP/FTP），更适合 API 调用和脚本编写，支持更多认证方式，且几乎在所有操作系统上都可用。

如何在 bash 脚本中使用 curl 下载文件？

使用 curl -fsSL -o file URL：-f 在 HTTP 错误时静默失败（不保存错误页面），-s 静默，-S 即使在静默模式下也显示错误，-L 跟随重定向。检查退出码：if ! curl -fsSL -o file URL; then echo "Download failed"; exit 1; fi。