curl 一次讲明白：请求、下载与调试，三个常见坑

在云服务器上排障，curl 是最顺手的工具：测接口通不通、下载文件、下个安装包，基本都靠它。但很多人只会 curl 网址 这一招，遇到 POST、重定向、超时就卡住。下面把最常用的三类用法一次讲明白。

1. 发一个请求：不止能 GET

最简单的用法是直接跟网址：

curl https://api.example.com/health

这会把响应体打出来。想看响应头，加 -i；只看状态码，用 -o /dev/null -s -w "%{http_code}"：

curl -i https://api.example.com/health
curl -o /dev/null -s -w "%{http_code}\n" https://api.example.com/health

发 POST 要带方法和数据：

curl -X POST https://api.example.com/login \
  -H 'Content-Type: application/json' \
  -d '{"user":"demo","pass":"123456"}'

-H 加请求头，-d 带请求体。记住：POST JSON 一定要配 Content-Type: application/json，不然服务端很可能按表单解析，直接报 400。

2. 下载文件：-O、-o 和断点续传

下载文件用 -O（按远程文件名保存）或 -o（指定本地文件名）：

curl -O https://example.com/package.tar.gz
curl -o /tmp/package.tar.gz https://example.com/package.tar.gz

大文件下载到一半断了，不用从头来，-C - 断点续传：

curl -C - -O https://example.com/bigfile.iso

还有一个容易忽略的：很多下载链接会 301 跳转，curl 默认不跟随，拿到的是一个空的跳转响应。下载前养成加 -L 的习惯：

curl -L -O https://example.com/latest.tar.gz

3. 调试：-v 看全过程，-w 量时间

接口不通，先别猜，用 -v 看完整握手过程：

curl -v https://api.example.com/health

-v 会打出 DNS 解析、TCP 连接、TLS 握手、请求头、响应头。卡在哪一步，一眼就能看出来：DNS 解析失败、连接超时、还是 TLS 证书有问题。

想量化慢在哪，用 -w 输出耗时：

curl -o /dev/null -s -w "DNS:%{time_namelookup} 连接:%{time_connect} 首字节:%{time_starttransfer} 总计:%{time_total}\n" https://api.example.com/health

这四个时间一对比，就知道慢在解析、建连还是服务端处理。

三个常见坑

坑一：忘了 -L，下载到一个空文件。 很多发行版、GitHub release 的下载链接都是 301 跳转。不加 -L，curl 只拿到跳转响应就停了，本地留下一个几百字节的“文件”。下载类命令，-L 默认加上。

坑二：POST 没加 Content-Type，服务端报 400。 -d 发过去的数据默认是 application/x-www-form-urlencoded。接口要 JSON 时，必须显式加 -H 'Content-Type: application/json'，否则服务端解析不到字段。

坑三：测内网接口不加超时，命令 hang 住。 服务端没响应时 curl 默认等很久，脚本里一卡就是几分钟。加两个超时兜底：

curl -m 10 --connect-timeout 3 https://api.example.com/health

--connect-timeout 3 是建连最多等 3 秒，-m 10 是整个请求最多 10 秒。写进脚本里尤其重要。

小结

curl 就记住三组：发请求用 -X/-H/-d，下载用 -L/-O/-C -，调试用 -v/-w，再配上超时。把这几组练熟，服务器上九成的接口调试和下载任务都不用再装别的工具。