curl 是什么
curl 是命令行的 URL 传输客户端，支持 HTTP/HTTPS、FTP/S、SCP/SFTP 等协议，能走代理、带 cookie、做认证、跟随重定向、断点续传。它之所以成为接口调试与下载的默认工具，在于无交互、输出可管道化、退出码可用：一条命令就能把结果写文件、交给 jq 解析，或只取状态码做判断。两个默认行为必须记牢——不跟随重定向，以及 HTTP 层的 4xx/5xx 不算命令失败，不额外处理就会误判成功。
基本信息
| 适用平台 | Linux、macOS、Windows 均可（curl 7.x/8.x）；多数发行版需单独安装 curl 包 |
|---|---|
| 命令语法 | curl [选项] URL |
| 常用选项 | -s 静默、-S 保留错误输出、-L 跟随重定向、-o 输出到文件、-O 用远端文件名、-I 只看响应头、-i 头与体都要、-v 详细过程、-X 指定方法、-H 自定义头、-d 请求体、-F 表单上传、-w 自定义输出 |
| 超时与重试 | --max-time 总超时、--connect-timeout 连接超时、--retry 重试次数、--retry-connrefused 连不上也重试 |
| 权限要求 | 普通用户即可执行；下载到受保护目录或绑定低位端口时才需要相应权限 |
典型使用场景
- 接口自测：-X POST 配 -H 与 -d 直接发 JSON，不用打开浏览器或 Postman 就能验证接口返回
- 健康检查：-o /dev/null 加 -w 取状态码与耗时，脚本据此判断服务是否可用
- 文件下载：-O 保留远端文件名，-L 跟随 CDN 跳转，-C - 断点续传大文件
- 证书与握手排查：-v 看 TLS 协商细节，--resolve 把域名强制解析到指定 IP 做灰度验证
- 抓取响应头：-I 只看头信息，确认状态码、Content-Length、缓存与跳转链路
- 内网访问：-x 指定代理，或配合 --cacert 使用自签 CA 访问内部 HTTPS 服务
常用示例
常用示例
curl -sS https://example.com # 静默但保留错误
curl -sS -o page.html https://example.com # 保存响应到文件
curl -sSL https://example.com # 跟随 301/302
curl -sS --max-time 10 --retry 2 https://api.example.com/health
curl -sf -o /dev/null -w 'code=%{http_code} time=%{time_total}s\n' https://example.com
curl -sS -X POST -H 'Content-Type: application/json' -d '{"id":1}' https://api.example.com/v1/query
curl -sSI https://example.com # 只看响应头
curl -sS -O -L https://example.com/big.iso # 下载并保留远端文件名
curl -sS -C - -O https://example.com/big.iso # 断点续传
curl -sS -v --resolve example.com:443:10.0.0.7 https://example.com # 指定解析结果做验证常用选项对照
| 选项 | 作用 | 注意 |
|---|---|---|
| -s | 静默模式，不显示进度条 | 会连错误信息一起吞掉，务必配 -S |
| -L | 跟随重定向，默认最多 50 跳 | 漏写时 301 响应体为空，容易被当成接口挂了 |
| -f | HTTP 状态码 4xx/5xx 时返回非 0 退出码 | 脚本判成功必须加 |
| -I | 只请求响应头（HEAD 方法） | 部分服务不支持 HEAD，会返回 405 |
| -w | 自定义输出格式变量 | 常与 -o /dev/null 搭配提取指标 |
| -k | 跳过 TLS 证书校验 | 仅测试环境可用，生产用 --cacert 指定信任链 |
常用输出变量
| 变量 | 含义 | 用途 |
|---|---|---|
| %{http_code} | HTTP 响应状态码 | 判断接口是否正常 |
| %{time_total} | 本次请求总耗时（秒） | 做性能基线与阈值告警 |
| %{time_connect} | TCP 连接建立耗时 | 区分是网络慢还是服务慢 |
| %{size_download} | 下载字节数 | 确认响应体是否完整 |
| %{num_redirects} | 重定向次数 | 排查跳转链路异常 |
curl 的退出码描述的是传输层面是否成功：能收到 HTTP 响应（哪怕是 500）通常仍返回 0。脚本里判断业务成功要加 -f 让 4xx/5xx 变成退出码 22，或解析 -w 输出的 http_code 自己判断，两者不要漏。
传参方式有三种，语义不同：-d 把内容作为请求体（默认表单编码，配合 -H 'Content-Type: application/json' 发 JSON），--data-binary 保留文件原样不做换行处理，-F 走 multipart 用于文件上传。跟老系统对接时表单与 JSON 的差异经常是 400 的根源。
URL 里带 & 时必须整体加引号，否则 shell 会把后半段当作后台执行并截断请求；带 token 的 URL 也会因此泄漏到命令历史里。敏感参数优先用 -H 'Authorization: ...' 或 --config 从文件读取。