命令行与文本处理 / 知识点
curl 参数速查手册
超时、失败与重试
对多数 HTTP 400+ 响应返回 curl 错误,并不输出错误响应 body。
-f / --fail · HTTP 错误时失败
什么时候查:当你在 curl 命令里看到 -f,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
对多数 HTTP 400+ 响应返回 curl 错误,并不输出错误响应 body。
参数形式
curl -f <URL>关键行为
常用于脚本和下载防止把错误页当成功数据。
示例
curl -fLsS -o app.bin https://example.com/app.bin易混参数
需要保留错误正文看 --fail-with-body。
风险与边界
认证等存在边界,不要把它当通用业务成功判断。
HTTP 400+ 时返回错误状态,同时保留响应正文。
--fail-with-body · HTTP 错误失败且保留正文
什么时候查:当你在 curl 命令里看到 --fail-with-body,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
HTTP 400+ 时返回错误状态,同时保留响应正文。
参数形式
curl --fail-with-body <URL>关键行为
API 调试与 CI 更容易看到服务端错误。
示例
curl --fail-with-body -sS https://example.com/api易混参数
与 --fail 互斥:前者保留 body,后者不保留。
风险与边界
目标 curl 版本过旧时不可用。
版本边界
7.76.0+
一次 curl 执行多个 URL 时,防止前面失败被后面成功掩盖。
--fail-early · 多传输尽早失败
什么时候查:当你在 curl 命令里看到 --fail-early,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
一次 curl 执行多个 URL 时,防止前面失败被后面成功掩盖。
参数形式
curl --fail-early <URL>关键行为
这是 global option。
示例
curl --fail-early --fail https://example.com/a https://example.com/b易混参数
--fail-early 负责多传输错误传播,--fail 负责 HTTP 状态。
风险与边界
单 URL 时价值不大。
对 curl 认定的 transient error 自动重试。
--retry · 重试临时错误
什么时候查:当你在 curl 命令里看到 --retry,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
对 curl 认定的 transient error 自动重试。
参数形式
curl --retry <NUM> <URL>关键行为
当前官方文档包括超时及 HTTP 408/429/500/502/503/504/522/524 等;默认 0 次。
示例
curl -sS --retry 3 https://example.com/api易混参数
连接拒绝需额外 --retry-connrefused;全错误重试看 --retry-all-errors。
风险与边界
非幂等请求必须先评估重复执行风险。
覆盖默认指数退避,改为固定等待。
--retry-delay · 固定重试间隔
什么时候查:当你在 curl 命令里看到 --retry-delay,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
覆盖默认指数退避,改为固定等待。
参数形式
curl --retry-delay <SECONDS> <URL>关键行为
值为 0 时使用默认 backoff。
示例
curl --retry 5 --retry-delay 2 https://example.com/易混参数
与 --retry-max-time 一个控制间隔,一个控制整体窗口。
风险与边界
间隔过短可能持续冲击故障服务。
限制 --retry 总体允许花费的时间。
--retry-max-time · 限制重试总窗口
什么时候查:当你在 curl 命令里看到 --retry-max-time,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
限制 --retry 总体允许花费的时间。
参数形式
curl --retry-max-time <SECONDS> <URL>关键行为
达到次数或时间边界后停止。
示例
curl --retry 5 --retry-max-time 20 https://example.com/易混参数
不要与单次 --max-time 混淆。
风险与边界
应按调用 SLA 设计。
配合 --retry,把 ECONNREFUSED 也视为临时错误。
--retry-connrefused · 连接拒绝也重试
什么时候查:当你在 curl 命令里看到 --retry-connrefused,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
配合 --retry,把 ECONNREFUSED 也视为临时错误。
参数形式
curl --retry-connrefused <URL>关键行为
适合等待刚启动的本地/容器服务。
示例
curl --retry 5 --retry-connrefused http://127.0.0.1:8080/health易混参数
默认 --retry 不会因 connection refused 自动重试。
风险与边界
长期 refused 通常是没监听或配置错误,不要无限重试。
配合 --retry 扩大重试错误范围。
--retry-all-errors · 所有错误都允许重试
什么时候查:当你在 curl 命令里看到 --retry-all-errors,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
配合 --retry 扩大重试错误范围。
参数形式
curl --retry-all-errors <URL>关键行为
官方明确把它视为非常激进的策略,可能造成重复发送/接收。
示例
curl --retry 3 --retry-all-errors https://example.com/易混参数
它不是 --retry 的默认最佳实践。
风险与边界
不要与重定向 stdin/stdout 盲目组合;非幂等请求有重复副作用风险。
版本边界
7.71.0+
重定向、HTTP 版本与 IP
自动跟随 3xx Location。
-L / --location · 跟随 HTTP 重定向
什么时候查:当你在 curl 命令里看到 -L,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
自动跟随 3xx Location。
参数形式
curl -L <URL>关键行为
最终返回重定向链末端响应。
示例
curl -sS -L https://example.com/old易混参数
--max-redirs 控制最大次数;--proto-redir 控制跳转协议。
风险与边界
跨主机重定向时注意认证 Header 和凭据边界。
限制 -L 最多跟随多少次。
--max-redirs · 限制重定向次数
什么时候查:当你在 curl 命令里看到 --max-redirs,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
限制 -L 最多跟随多少次。
参数形式
curl --max-redirs <NUM> <URL>关键行为
超过限制后失败。
示例
curl -L --max-redirs 5 https://example.com/易混参数
只有跟随重定向时有意义。
风险与边界
设置过低可能误伤合法登录/CDN 流程。
控制本次 curl 可以使用哪些 URL 协议。
--proto · 限制允许协议
什么时候查:当你在 curl 命令里看到 --proto,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
控制本次 curl 可以使用哪些 URL 协议。
参数形式
curl --proto <LIST> <URL>关键行为
=https 可重置为仅 HTTPS。
示例
curl --proto '=https' -sS https://example.com/易混参数
--proto-redir 只限制重定向后的协议。
风险与边界
处理外部输入 URL、下载器和自动化时是重要安全边界。
控制 Location 跳转允许进入哪些协议。
--proto-redir · 限制重定向协议
什么时候查:当你在 curl 命令里看到 --proto-redir,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
控制 Location 跳转允许进入哪些协议。
参数形式
curl --proto-redir <LIST> <URL>关键行为
可阻止 HTTP(S) 跳到 file/ftp 等意外协议。
示例
curl -L --proto-redir '=https' https://example.com/易混参数
与 --proto 搭配可构建完整白名单。
风险与边界
按业务实际设计允许列表。
要求使用 HTTP/1.1。
--http1.1 · 强制 HTTP/1.1
什么时候查:当你在 curl 命令里看到 --http1.1,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
要求使用 HTTP/1.1。
参数形式
curl --http1.1 <URL>关键行为
用于排查 HTTP/2/3 与网关/代理兼容问题。
示例
curl --http1.1 -sS -I https://example.com/易混参数
与 HTTP2/HTTP3 强制选项互斥。
风险与边界
排障用,不应无理由长期降级协议。
让 curl 尝试使用 HTTP/2。
--http2 · 尝试 HTTP/2
什么时候查:当你在 curl 命令里看到 --http2,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
让 curl 尝试使用 HTTP/2。
参数形式
curl --http2 <URL>关键行为
HTTPS 通常通过 ALPN 协商,实际能力取决于 libcurl 编译特性。
示例
curl --http2 -sS -I https://example.com/易混参数
先用 curl --version 看 Features 是否有 HTTP2。
风险与边界
最终协议用 verbose/write-out 确认。
直接按已知 HTTP/2 能力建立连接。
--http2-prior-knowledge · 预先假定 HTTP/2
什么时候查:当你在 curl 命令里看到 --http2-prior-knowledge,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
直接按已知 HTTP/2 能力建立连接。
参数形式
curl --http2-prior-knowledge <URL>关键行为
适合明确知道服务端支持 HTTP/2 的场景。
示例
curl --http2-prior-knowledge http://example.com/易混参数
与普通 --http2 区别是“不先按常规方式协商/探测”。
风险与边界
对不支持的服务端会直接失败。
对 HTTPS 尝试 HTTP/3,连接慢或失败时允许回退到 HTTP/2/1.1。
--http3 · 优先 HTTP/3,可回退
什么时候查:当你在 curl 命令里看到 --http3,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
对 HTTPS 尝试 HTTP/3,连接慢或失败时允许回退到 HTTP/2/1.1。
参数形式
curl --http3 <URL>关键行为
curl 会保留更早 HTTP 版本的回退路径。
示例
curl --http3 -sS -I https://example.com/易混参数
--http3-only 不允许回退,这是最关键区别。
风险与边界
需要 curl 构建支持 HTTP/3;仅 HTTPS。
版本边界
7.66.0+
HTTPS 只使用 HTTP/3,QUIC 建连失败就失败。
--http3-only · 仅允许 HTTP/3
什么时候查:当你在 curl 命令里看到 --http3-only,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
HTTPS 只使用 HTTP/3,QUIC 建连失败就失败。
参数形式
curl --http3-only <URL>关键行为
不会尝试 HTTP/2 或 HTTP/1.1。
示例
curl --http3-only -sS -I https://example.com/易混参数
用于严格验证 HTTP/3;普通请求更适合 --http3。
风险与边界
依赖 HTTP/3 编译支持。
版本边界
7.88.0+
DNS、连接与代理
为特定 host+port 注入解析结果,可视作命令行临时 /etc/hosts。
--resolve · 临时指定 host:port 到 IP
什么时候查:当你在 curl 命令里看到 --resolve,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
为特定 host+port 注入解析结果,可视作命令行临时 /etc/hosts。
参数形式
curl --resolve <HOST:PORT:ADDR> <URL>关键行为
连接使用指定 IP,但 URL 主机名、HTTP Host、TLS SNI 仍保持原域名。
示例
curl --resolve example.com:443:192.0.2.20 https://example.com/易混参数
--connect-to 可以连端口一起改写;--resolve 更像替换 DNS 结果。
风险与边界
端口必须匹配实际请求端口;IPv6 地址按 curl 语法加括号。
把原本连接 H1:P1 的请求改连 H2:P2。
--connect-to · 改写底层连接目标
什么时候查:当你在 curl 命令里看到 --connect-to,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
把原本连接 H1:P1 的请求改连 H2:P2。
参数形式
curl --connect-to <H1:P1:H2:P2> <URL>关键行为
只影响底层连接,不改变 TLS SNI、证书验证主机名和应用逻辑主机。
示例
curl --connect-to example.com:443:origin.internal:8443 https://example.com/易混参数
--resolve 主要改地址;--connect-to 可同时改主机和端口。
风险与边界
高级排障时必须理解“逻辑主机”和“连接目标”区别。
让 curl 通过代理访问目标。
-x / --proxy · 指定代理
什么时候查:当你在 curl 命令里看到 -x,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
让 curl 通过代理访问目标。
参数形式
curl -x <PROXY> <URL>关键行为
支持 HTTP/HTTPS 等代理形式,具体取决于构建。
示例
curl -x http://127.0.0.1:8080 https://example.com/易混参数
--noproxy 设置绕过列表;SOCKS 用对应 socks 参数。
风险与边界
敏感请求只使用可信代理。