命令行与文本处理 / 知识点
curl 命令速查手册
上传、下载与文件
curl --limit-rate <RATE> <URL>限制单次传输的平均速度,减少对链路的影响。
限制下载速度
限制单次传输的平均速度,减少对链路的影响。
基本语法
curl --limit-rate <RATE> <URL>高频用法
curl --limit-rate 2M -o large.bin https://example.com/large.bin预期结果:
下载速率大致受限于 2 MiB/s 级别。读取方法
适合生产环境临时拉取大文件。
使用说明
限速不是 QoS 保证;并发多个 curl 进程会分别限速。
curl -T <FILE> <URL>使用 --upload-file/-T 把文件上传到目标 URL。
直接上传文件
使用 --upload-file/-T 把文件上传到目标 URL。
基本语法
curl -T <FILE> <URL>高频用法
curl -sS -T artifact.bin https://example.com/upload/artifact.bin预期结果:
服务端按目标协议接收文件。读取方法
HTTP 场景通常表现为 PUT 风格上传,具体取决于服务端。
使用说明
上传前确认服务端 API 约定;不要把 multipart API 错用成 -T。
curl -T - <URL>把标准输入作为上传内容,无需先生成临时文件。
从标准输入上传
把标准输入作为上传内容,无需先生成临时文件。
基本语法
curl -T - <URL>高频用法
tar -czf - ./logs | curl -T - https://example.com/upload/logs.tar.gz预期结果:
管道输出直接成为上传数据。读取方法
适合流式归档、动态生成内容。
风险与边界
网络中断后通常难以自动从 stdin 恢复;谨慎结合重试。
curl --create-dirs -o <PATH> <URL>保存文件时自动创建本地缺失的父目录。
创建输出目录
保存文件时自动创建本地缺失的父目录。
基本语法
curl --create-dirs -o <PATH> <URL>高频用法
curl --create-dirs -o downloads/2026/app.bin https://example.com/app.bin预期结果:
目标父目录不存在时被创建,文件写入指定位置。读取方法
适合脚本化下载层级目录。
使用说明
输出路径仍应由可信输入生成,防止路径穿越或写到意外位置。
curl -R -o <FILE> <URL>若响应提供 Last-Modified,则尝试把本地文件时间设置为远端时间。
保留远端修改时间
若响应提供 Last-Modified,则尝试把本地文件时间设置为远端时间。
基本语法
curl -R -o <FILE> <URL>高频用法
curl -R -o archive.bin https://example.com/archive.bin预期结果:
下载完成后本地 mtime 可能与服务器 Last-Modified 一致。读取方法
适合镜像、归档或依赖时间戳的同步。
风险与边界
Last-Modified 是服务器声明值,不应作为安全可信时间来源。
响应与输出
curl -i <URL>把响应头一起输出到标准输出,适合快速 API 排障。
同时显示响应头和正文
把响应头一起输出到标准输出,适合快速 API 排障。
基本语法
curl -i <URL>高频用法
curl -sS -i https://example.com/api预期结果:
依次显示 HTTP 状态行、Header、空行和正文。读取方法
-i 与 -I 不同:-i 仍发送正常请求并保留正文。
使用说明
正文是二进制文件时不要直接 -i 打到终端。
curl -D <FILE> <URL>把响应头保存到独立文件,同时把响应体保存到另一个文件。
单独保存响应头
把响应头保存到独立文件,同时把响应体保存到另一个文件。
基本语法
curl -D <FILE> <URL>高频用法
curl -sS -D headers.txt -o body.json https://example.com/api预期结果:
生成 `headers.txt` 和 `body.json`。读取方法
非常适合保留可复现的 HTTP 现场。
风险与边界
Header 中可能包含 Set-Cookie、内部地址或跟踪信息,分享前应脱敏。
curl -w '%{http_code}' ...忽略正文,只输出 HTTP 状态码。
只输出 HTTP 状态码
忽略正文,只输出 HTTP 状态码。
基本语法
curl -w '%{http_code}' ...高频用法
curl -sS -o /dev/null -w '%{http_code}
' https://example.com/health预期结果:
例如 `200`、`404`、`503`。读取方法
适合脚本健康检查。
风险与边界
HTTP 500 默认仍可能让 curl 进程退出码为 0;需要失败语义时结合 --fail 或 --fail-with-body。
curl -L -w '%{url_effective}' ...跟随重定向后输出实际最终 URL。
输出最终 URL
跟随重定向后输出实际最终 URL。
基本语法
curl -L -w '%{url_effective}' ...高频用法
curl -sS -L -o /dev/null -w '%{url_effective}
' https://example.com/download预期结果:
输出最终落到的完整 URL。读取方法
适合定位 CDN、登录跳转或下载链接链路。
风险与边界
最终 URL 可能包含签名参数等敏感信息,写日志前注意脱敏。
curl -w <FORMAT> <URL>查看本次请求实际连接到的远端地址。
输出远端 IP 和端口
查看本次请求实际连接到的远端地址。
基本语法
curl -w <FORMAT> <URL>高频用法
curl -sS -o /dev/null -w 'remote=%{remote_ip}:%{remote_port}
' https://example.com/预期结果:
输出类似 `remote=192.0.2.20:443`。读取方法
CDN、多 A/AAAA 记录、DNS 轮询排障时非常有用。
风险与边界
代理场景中该地址可能是代理而非最终源站,需结合请求拓扑解释。
curl -sS <URL>隐藏进度条等常规噪音,但在失败时仍输出错误信息。
静默输出但保留错误
隐藏进度条等常规噪音,但在失败时仍输出错误信息。
基本语法
curl -sS <URL>高频用法
curl -sS https://example.com/api预期结果:
成功时只有响应内容;失败时仍显示 curl 错误。读取方法
-sS 是脚本中比单独 -s 更稳妥的常用组合。
风险与边界
它不会让 HTTP 4xx/5xx 自动变成 curl 失败。
超时、重试与错误处理
curl --fail <URL>让 HTTP 400 及以上响应通常返回 curl 错误码,并隐藏错误响应正文。
HTTP 错误时失败
让 HTTP 400 及以上响应通常返回 curl 错误码,并隐藏错误响应正文。
基本语法
curl --fail <URL>高频用法
curl --fail -sS https://example.com/api预期结果:
遇到 HTTP 错误时命令以非零状态结束。读取方法
适合下载和脚本中阻止把错误页当成功结果。
风险与边界
若需要同时保留服务端错误 body,使用 --fail-with-body。
curl --fail-with-body <URL>HTTP 400+ 时既保留响应正文,又让 curl 返回错误状态。
HTTP 错误时保留正文并失败
HTTP 400+ 时既保留响应正文,又让 curl 返回错误状态。
基本语法
curl --fail-with-body <URL>高频用法
curl --fail-with-body -sS https://example.com/api预期结果:
服务端错误 body 可见,同时 curl 退出码为非零。读取方法
API 调试与 CI 中通常比 --fail 更容易定位服务端错误。
风险与边界
较旧 curl 版本可能没有此选项;脚本部署前确认目标环境版本。
curl --connect-timeout <SEC> <URL>限制 DNS 后连接建立阶段允许等待的时间。
限制连接超时
限制 DNS 后连接建立阶段允许等待的时间。
基本语法
curl --connect-timeout <SEC> <URL>高频用法
curl -sS --connect-timeout 3 https://example.com/api预期结果:
连接无法及时建立时 curl 以超时错误结束。读取方法
适合避免健康检查长时间卡在 TCP/TLS 建连。
风险与边界
它不是整个请求的总超时;总时长还要配合 --max-time。
curl --max-time <SEC> <URL>限制整个传输最多持续多久。
限制请求总时长
限制整个传输最多持续多久。
基本语法
curl --max-time <SEC> <URL>高频用法
curl -sS --max-time 10 https://example.com/api预期结果:
超过总时限时 curl 退出并返回超时错误。读取方法
适合自动化任务、健康检查和防止接口无限等待。
风险与边界
超时可能发生在下载中途,写文件场景应检查是否留下部分文件。
curl --speed-limit <BPS> --speed-time <SEC> <URL>当传输速度连续一段时间低于阈值时主动失败。
检测低速卡死
当传输速度连续一段时间低于阈值时主动失败。
基本语法
curl --speed-limit <BPS> --speed-time <SEC> <URL>高频用法
curl --speed-limit 1024 --speed-time 15 -o file.bin https://example.com/file.bin预期结果:
若连续 15 秒低于约 1024 B/s,curl 终止传输。读取方法
比单纯总超时更适合检测连接没断但几乎不传数据的场景。
风险与边界
阈值应按实际链路和文件大小设置,过严会误杀慢链路。
curl --retry <N> <URL>对 curl 认定的临时错误及部分临时 HTTP 状态自动重试。
自动重试临时错误
对 curl 认定的临时错误及部分临时 HTTP 状态自动重试。
基本语法
curl --retry <N> <URL>高频用法
curl -sS --retry 3 https://example.com/api预期结果:
首次失败后按退避策略再次尝试,最多额外重试指定次数。读取方法
适合 GET、下载等幂等操作提高抗瞬时故障能力。
风险与边界
POST/支付/创建订单等非幂等操作必须先确认重复执行是否安全。
curl --retry <N> --retry-connrefused <URL>把连接被拒绝也视为可重试的临时错误。
连接拒绝时也重试
把连接被拒绝也视为可重试的临时错误。
基本语法
curl --retry <N> --retry-connrefused <URL>高频用法
curl -sS --retry 5 --retry-connrefused http://127.0.0.1:8080/health预期结果:
服务尚未启动时可等待后续重试成功。读取方法
适合容器启动等待、本地服务 readiness 场景。
风险与边界
长期拒绝通常是服务未监听或配置错误,不要用无限重试掩盖根因。
curl --retry <N> --retry-all-errors <URL>在 --retry 基础上扩大可重试错误范围。
对所有错误启用重试
在 --retry 基础上扩大可重试错误范围。
基本语法
curl --retry <N> --retry-all-errors <URL>高频用法
curl -sS --retry 3 --retry-all-errors https://example.com/api预期结果:
更多类型失败会进入重试流程。读取方法
只应在明确理解请求幂等性与输入/输出行为时使用。
风险与边界
这是激进策略;可能导致重复提交或输出重复,尤其不要盲目用于重定向 stdin/stdout。
curl --retry <N> --retry-max-time <SEC> <URL>在多次重试之外再限制整个重试窗口。
限制重试总时间
在多次重试之外再限制整个重试窗口。
基本语法
curl --retry <N> --retry-max-time <SEC> <URL>高频用法
curl -sS --retry 5 --retry-max-time 20 https://example.com/api预期结果:
达到重试次数或最大重试时间后停止。读取方法
适合有明确 SLA 的健康检查和部署等待。
风险与边界
仍需结合 --connect-timeout、--max-time 理解单次传输与整体窗口。