curl 命令速查:按场景查 GET/POST/认证/下载与调试

curl 的 man 手册有两百多个选项,但日常扒接口、调 API 真正会敲的就那十几个。问题在于你很少能一口气记全,往往是某个场景突然卡住:POST 发出去服务端说 body 空、下载到一半断了、跟着跳转却拿到一段占位 HTML。这篇按场景把常用选项捋一遍,需要哪块直接跳哪块。

最基础的 GET 与查看返回

最短的一发就是 curl https://api.example.com/items,默认就是 GET,结果打到标准输出。调接口时光看 body 不够,你还想知道状态码和响应头:

curl -i https://api.example.com/items      # 连响应头一起打
curl -I https://api.example.com/items      # 只要响应头(HEAD)
curl -s https://api.example.com/items      # 安静模式,不打进度条
curl -v https://api.example.com/items      # 啰嗦模式,连请求行都给你看

这里有个坑:-s 会把真实错误也一起吞掉,排查问题时永远 -sS 一起写,这样进度条没了但出错还会提示。想知道返回的具体含义,可以对着 /zh/t/http-status-explorer/ 把 400、415、502 这些码逐个查清楚。

POST 发数据,JSON 怎么发对

这是翻车最多的一块。发 JSON 的 POST,方法、Content-Type、body 三个要素必须对齐,缺一个就报错:

curl -X POST -H "Content-Type: application/json" -d '{"name":"toolora","ok":true}' https://api.example.com/items

最常见的失败是写了 -X POST 却忘了 -d,服务端拿到空 body 直接 400。其实更干净的写法是干脆别写 -X,光写 -d 就隐含 POST,-X 留给 PUT、PATCH、DELETE 这些 curl 推断不出来的方法。第二档失败是发了 -d 却没带 Content-Type,API 当成表单解析返回 415。还有一个误区:-d 不会帮你做 URL 编码,带空格和 & 的值要用 --data-urlencode "q=hello world"。如果是表单文件上传,改用 -F "file=@./report.pdf",这里 @ 是必须的,不加就当字面字符串。

加 header 与认证

-H 加任意 header,认证最常用的是 Bearer token:

curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me
curl -u user:pass https://api.example.com/private        # Basic 认证

token 务必从环境变量读,别把字符串直接贴进命令行,.bash_history 是最容易泄露密钥的地方。

下载文件、跟随重定向、带 cookie

下载相关的几个选项各管各的:

curl -O https://example.com/file.zip       # 用远端文件名存盘
curl -o out.zip https://example.com/file.zip   # 自己指定文件名
curl -L https://example.com/file.zip        # 跟随 301/302 重定向
curl -C - -O https://example.com/big.iso    # 断点续传,接着上次的下

-L 这块要注意:不带它,服务端返回 302 时你拿到的只是一段重定向占位,不是真内容。但跟随跳转到不同 host 时,curl 会故意把 Authorization 丢掉,这是对的安全默认,只有完全信任跳转链才用 --location-trusted。带 cookie 模拟一次浏览器会话,用 -b 读、-c 写,两个一起用就能保持登录态:

curl -c jar.txt -d 'user=a&pass=b' https://example.com/login   # 登录,存 cookie
curl -b jar.txt https://example.com/dashboard                  # 带着 cookie 访问

调试接口:让 curl 告诉你慢在哪

接口慢但应用日志看着正常,这时 -w 的计时模板最好使。我自己排查内网延迟就靠这一行,有次看到 time_namelookup 飙到 1.8 秒而 connect 和 starttransfer 都很小,一下就定位到瓶颈是 DNS 解析而不是服务本身,工单直接开给 DNS 那边:

curl -w 'dns:%{time_namelookup} connect:%{time_connect} tls:%{time_appconnect} ttfb:%{time_starttransfer} total:%{time_total}\n' -o /dev/null -s https://example.com

一行就能看出是 DNS、TCP、TLS 还是服务端慢。请求一直挂着不超时,永远成对加 --connect-timeout 5 --max-time 30,前者卡握手,后者卡总时长,瞬时故障再叠 --retry 3 --retry-all-errors。DNS 这一环想深挖,可以配合 /zh/t/dns-record-explainer/ 看清域名解析的每条记录。

把这些选项收进工具箱

上面只是高频场景,完整的 80+ 选项、每条对应的常见坑和可拷贝例子,都在 /zh/t/curl-cheatsheet/ 里,搜索框跨命令、说明、坑、例子四个字段一起过滤,输入关键词哪怕只在例子里也能命中。命令行用得多的话,bash 本身的写法也值得顺手过一遍,见 /zh/t/bash-cheatsheet/。把 curl 这十几个高频选项练成肌肉记忆,调接口这件事就从"猜一下午"变成"五分钟看一眼"。

Made by Toolora · Updated 2026-06-13