命令行与文本处理 / 知识点
curl 参数速查手册
Header、响应与输出
用 URL 路径最后一段作为本地文件名。
-O / --remote-name · 使用远端文件名
什么时候查:当你在 curl 命令里看到 -O,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
用 URL 路径最后一段作为本地文件名。
参数形式
curl -O <URL>关键行为
适合 URL 已包含可信制品名。
示例
curl -fLO https://example.com/releases/app.tar.gz易混参数
与 -o 相比无法自行指定最终名字。
风险与边界
不要对不可信 URL 直接在敏感目录执行 -O。
配合 -O 时允许服务器建议本地文件名。
-J / --remote-header-name · 使用 Content-Disposition 文件名
什么时候查:当你在 curl 命令里看到 -J,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
配合 -O 时允许服务器建议本地文件名。
参数形式
curl -J <URL>关键行为
常用于下载接口的业务文件名。
示例
curl -fLJO https://example.com/download/123易混参数
通常与 -O 搭配,而不是替代。
风险与边界
服务器返回的文件名属于外部输入,下载目录要谨慎。
传输以错误结束时删除本次输出文件。
--remove-on-error · 失败时删除输出文件
什么时候查:当你在 curl 命令里看到 --remove-on-error,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
传输以错误结束时删除本次输出文件。
参数形式
curl --remove-on-error <URL>关键行为
避免自动化误用半截文件。
示例
curl --fail --remove-on-error -o package.bin https://example.com/package.bin易混参数
它解决“失败残留文件”,不决定 HTTP 什么状态算失败。
风险与边界
如果目标原本存在,应先理解覆盖行为。
版本边界
7.83.0+
使用 -o 保存到多级路径时自动创建缺失目录。
--create-dirs · 自动创建父目录
什么时候查:当你在 curl 命令里看到 --create-dirs,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
使用 -o 保存到多级路径时自动创建缺失目录。
参数形式
curl --create-dirs <URL>关键行为
适合批量下载分层目录。
示例
curl --create-dirs -o downloads/2026/app.bin https://example.com/app.bin易混参数
只负责建目录,不验证路径是否可信。
风险与边界
外部输入生成输出路径时仍需防路径穿越。
从指定字节位置继续传输。
-C / --continue-at · 从断点继续传输
什么时候查:当你在 curl 命令里看到 -C,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
从指定字节位置继续传输。
参数形式
curl -C <OFFSET|-> <URL>关键行为
-C - 让 curl 尝试自动判断续传偏移。
示例
curl -C - -o large.iso https://example.com/large.iso易混参数
续传依赖协议和服务器能力;HTTP 上传没有通用可靠续传标准。
风险与边界
远端文件变化时续传可能损坏,完成后应校验。
下载后尝试把本地 mtime 设置成远端时间。
-R / --remote-time · 保留远端修改时间
什么时候查:当你在 curl 命令里看到 -R,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
下载后尝试把本地 mtime 设置成远端时间。
参数形式
curl -R <URL>关键行为
HTTP 常使用 Last-Modified。
示例
curl -R -o archive.bin https://example.com/archive.bin易混参数
只影响本地时间戳,不改变文件内容。
风险与边界
远端声明时间不应被当作可信安全时间源。
认证、Cookie 与凭据
为 HTTP、FTP 等提供用户凭据。
-u / --user · 目标服务用户名和密码
什么时候查:当你在 curl 命令里看到 -u,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
为 HTTP、FTP 等提供用户凭据。
参数形式
curl -u <USER:PASSWORD> <URL>关键行为
HTTP 可与 Basic、Digest、NTLM、Negotiate 等组合。
示例
curl -u alice https://example.com/private易混参数
只写用户名时 curl 可交互询问密码,比明文 user:password 更安全。
风险与边界
密码直接写在命令行可能泄露到 Shell 历史或进程信息。
明确使用 HTTP Basic 认证。
--basic · HTTP Basic Auth
什么时候查:当你在 curl 命令里看到 --basic,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
明确使用 HTTP Basic 认证。
参数形式
curl --basic <URL>关键行为
通常与 -u 一起。
示例
curl --basic -u alice:secret https://example.com/private易混参数
Basic 仅编码凭据,不提供加密;安全性依赖 HTTPS。
风险与边界
不要在明文 HTTP 上发送真实密码。
使用 HTTP Digest 认证。
--digest · HTTP Digest Auth
什么时候查:当你在 curl 命令里看到 --digest,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
使用 HTTP Digest 认证。
参数形式
curl --digest <URL>关键行为
通常先收到 challenge,再完成认证。
示例
curl --digest -u alice:secret https://example.com/private易混参数
与 Basic/NTLM/Negotiate 是不同认证机制。
风险与边界
仍应在 TLS 上使用。
先探测服务端支持的认证机制,再选择方式。
--anyauth · 自动选择认证方式
什么时候查:当你在 curl 命令里看到 --anyauth,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
先探测服务端支持的认证机制,再选择方式。
参数形式
curl --anyauth <URL>关键行为
通常会额外产生一次请求/往返。
示例
curl --anyauth -u alice:secret https://example.com/private易混参数
与明确指定 --basic/--digest/... 相比更自动。
风险与边界
上传 stdin 时可能需要重发数据且无法 rewind,不建议盲目使用。
为支持 SASL OAuth2 的协议提供 Bearer Token。
--oauth2-bearer · OAuth2 Bearer Token
什么时候查:当你在 curl 命令里看到 --oauth2-bearer,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
为支持 SASL OAuth2 的协议提供 Bearer Token。
参数形式
curl --oauth2-bearer <TOKEN> <URL>关键行为
HTTP REST API 更常直接使用 Authorization Header。
示例
curl --oauth2-bearer '<TOKEN>' imaps://mail.example.com/易混参数
HTTP API 常见写法仍是 -H Authorization: Bearer ...。
风险与边界
Token 属于高敏感凭据。
发送 Cookie 字符串,或从 Cookie 文件加载。
-b / --cookie · 发送或读取 Cookie
什么时候查:当你在 curl 命令里看到 -b,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
发送 Cookie 字符串,或从 Cookie 文件加载。
参数形式
curl -b <DATA|FILE> <URL>关键行为
curl 会按域名、路径等规则发送匹配 Cookie。
示例
curl -sS -b 'session=abc123' https://example.com/account易混参数
-b 负责读/发送;-c 负责写 cookie jar。
风险与边界
Session Cookie 等同登录凭据,Cookie 文件需限制权限。
请求结束后把 Cookie 写入 jar 文件。
-c / --cookie-jar · 保存 Cookie
什么时候查:当你在 curl 命令里看到 -c,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
请求结束后把 Cookie 写入 jar 文件。
参数形式
curl -c <FILE> <URL>关键行为
适合跨多次 curl 调用保持会话。
示例
curl -sS -c cookies.txt https://example.com/login易混参数
通常和后续 -b cookies.txt 配合。
风险与边界
Cookie jar 不应提交到 Git 或共享。
从 Cookie 文件加载时忽略没有过期时间的 session Cookie。
-j / --junk-session-cookies · 丢弃会话 Cookie
什么时候查:当你在 curl 命令里看到 -j,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
从 Cookie 文件加载时忽略没有过期时间的 session Cookie。
参数形式
curl -j <URL>关键行为
效果类似新浏览器会话。
示例
curl -j -b cookies.txt https://example.com/易混参数
只在读取 cookie 文件时有意义。
风险与边界
不会删除服务器本次新返回的 Cookie。
允许从默认 netrc 文件读取目标主机凭据。
-n / --netrc · 读取 ~/.netrc 凭据
什么时候查:当你在 curl 命令里看到 -n,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
允许从默认 netrc 文件读取目标主机凭据。
参数形式
curl -n <URL>关键行为
避免把密码直接写进命令行。
示例
curl --netrc https://example.com/private易混参数
--netrc-file 可指定其他文件。
风险与边界
netrc 本身是敏感文件,需严格权限。
使用指定文件代替默认 ~/.netrc。
--netrc-file · 指定 netrc 文件
什么时候查:当你在 curl 命令里看到 --netrc-file,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
使用指定文件代替默认 ~/.netrc。
参数形式
curl --netrc-file <FILE> <URL>关键行为
适合 CI、容器 secret 和临时凭据。
示例
curl --netrc-file /run/secrets/curl.netrc https://example.com/private易混参数
比默认 netrc 更容易隔离任务凭据。
风险与边界
任务结束后按策略清理临时凭据文件。
超时、失败与重试
限制连接建立阶段允许花费的时间。
--connect-timeout · 连接阶段超时
什么时候查:当你在 curl 命令里看到 --connect-timeout,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
限制连接建立阶段允许花费的时间。
参数形式
curl --connect-timeout <SECONDS> <URL>关键行为
用于避免 DNS 后 TCP/TLS 建连长期卡住。
示例
curl -sS --connect-timeout 3 https://example.com/易混参数
它不是总请求超时;总时长看 --max-time。
风险与边界
设置过短会在慢网络制造误失败。
限制一次传输的最长总时长。
-m / --max-time · 总传输超时
什么时候查:当你在 curl 命令里看到 -m,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
限制一次传输的最长总时长。
参数形式
curl -m <SECONDS> <URL>关键行为
可能在连接、等待首字节或下载中触发。
示例
curl -sS --max-time 10 https://example.com/api易混参数
与 --connect-timeout 分别控制整体和建连。
风险与边界
文件下载超时可能留下部分文件,可配合 --remove-on-error。
与 --speed-time 配合检测长期低速卡死。
--speed-limit · 最低传输速度
什么时候查:当你在 curl 命令里看到 --speed-limit,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
与 --speed-time 配合检测长期低速卡死。
参数形式
curl --speed-limit <BPS> <URL>关键行为
速度持续低于阈值达到时间窗口后失败。
示例
curl --speed-limit 1024 --speed-time 15 -o file.bin https://example.com/file.bin易混参数
与总超时不同,它关心“持续低速”。
风险与边界
阈值应按真实链路设置。
定义低速判定需要持续多久。
--speed-time · 低速持续窗口
什么时候查:当你在 curl 命令里看到 --speed-time,或者需要确认它的默认行为、易混参数和安全边界时查这一条。
作用
定义低速判定需要持续多久。
参数形式
curl --speed-time <SECONDS> <URL>关键行为
需结合 --speed-limit 理解。
示例
curl --speed-limit 1024 --speed-time 15 https://example.com/易混参数
一个定义速度阈值,一个定义持续时间。
风险与边界
过短会把正常抖动判成故障。