curl - HTTP 客户端

用于发起 HTTP 请求和传输数据的命令行工具。

基础请求

GET 请求

# 简单 GET 请求
curl https://api.example.com

# 将响应保存到文件
curl https://example.com -o output.html
curl https://example.com/file.zip -O  # 使用远程文件名

# 跟随重定向
curl -L https://example.com

# 显示响应头
curl -i https://example.com

# 仅显示响应头
curl -I https://example.com

# 详细输出（用于调试）
curl -v https://example.com

POST 请求

# 带数据的 POST 请求
curl -X POST https://api.example.com/users 
  -d "name=John&email=john@example.com"

# POST JSON 数据
curl -X POST https://api.example.com/users 
  -H "Content-Type: application/json" 
  -d '{"name":"John","email":"john@example.com"}'

# 从文件读取数据进行 POST
curl -X POST https://api.example.com/users 
  -H "Content-Type: application/json" 
  -d @data.json

# 表单文件上传
curl -X POST https://api.example.com/upload 
  -F "file=@document.pdf" 
  -F "description=My document"

其他 HTTP 方法

# PUT 请求
curl -X PUT https://api.example.com/users/1 
  -H "Content-Type: application/json" 
  -d '{"name":"Jane"}'

# DELETE 请求
curl -X DELETE https://api.example.com/users/1

# PATCH 请求
curl -X PATCH https://api.example.com/users/1 
  -H "Content-Type: application/json" 
  -d '{"email":"newemail@example.com"}'

请求头与身份验证

自定义请求头

# 添加自定义请求头
curl -H "User-Agent: MyApp/1.0" https://example.com

# 多个请求头
curl -H "Accept: application/json" 
     -H "Authorization: Bearer token123" 
     https://api.example.com

身份验证

# Basic Auth
curl -u username:password https://api.example.com

# Bearer Token
curl -H "Authorization: Bearer YOUR_TOKEN" 
  https://api.example.com

# API Key 放在请求头中
curl -H "X-API-Key: your_api_key" 
  https://api.example.com

# API Key 放在 URL 中
curl "https://api.example.com?api_key=your_key"

高级功能

超时与重试

# 连接超时（秒）
curl --connect-timeout 10 https://example.com

# 整个操作最大耗时（秒）
curl --max-time 30 https://example.com

# 失败时自动重试
curl --retry 3 https://example.com

# 设置重试间隔（秒）
curl --retry 3 --retry-delay 5 https://example.com

Cookies

# 发送 Cookie
curl -b "session=abc123" https://example.com

# 将 Cookie 保存至文件
curl -c cookies.txt https://example.com

# 从文件加载 Cookie
curl -b cookies.txt https://example.com

# 同时加载并保存 Cookie
curl -b cookies.txt -c cookies.txt https://example.com

代理

# 使用 HTTP 代理
curl -x http://proxy.example.com:8080 https://api.example.com

# 代理认证
curl -x http://proxy:8080 -U user:pass https://api.example.com

# 使用 SOCKS 代理
curl --socks5 127.0.0.1:1080 https://api.example.com

SSL/TLS

# 忽略 SSL 证书错误（生产环境不推荐）
curl -k https://self-signed.example.com

# 指定 SSL 版本
curl --tlsv1.2 https://example.com

# 使用客户端证书
curl --cert client.crt --key client.key https://example.com

# 显示 SSL 握手详情
curl -v https://example.com 2>&1 | grep -i ssl

响应处理

输出格式化

# 静默模式（不显示进度条）
curl -s https://api.example.com

# 仅显示 HTTP 状态码
curl -s -o /dev/null -w "%{http_code}" https://example.com

# 自定义输出格式
curl -w "\nTime: %{time_total}s\nStatus: %{http_code}\n" 
  https://example.com

# 美化打印 JSON（配合 jq 使用）
curl -s https://api.example.com | jq '.'

范围请求（Range Requests）

# 下载指定字节范围
curl -r 0-1000 https://example.com/large-file.zip

# 断点续传
curl -C - -O https://example.com/large-file.zip

文件操作

下载文件

# 下载文件
curl -O https://example.com/file.zip

# 下载并指定本地文件名
curl -o myfile.zip https://example.com/file.zip

# 同时下载多个文件
curl -O https://example.com/file1.zip 
     -O https://example.com/file2.zip

# 继续中断的下载
curl -C - -O https://example.com/large-file.zip

上传文件

# FTP 上传
curl -T file.txt ftp://ftp.example.com/upload/

# HTTP PUT 上传
curl -T file.txt https://example.com/upload

# 表单方式上传文件
curl -F "file=@document.pdf" https://example.com/upload

测试与调试

API 测试

# 测试 REST API
curl -X GET https://api.example.com/users
curl -X GET https://api.example.com/users/1
curl -X POST https://api.example.com/users -d @user.json
curl -X PUT https://api.example.com/users/1 -d @updated.json
curl -X DELETE https://api.example.com/users/1

# 启用详细输出进行测试
curl -v -X POST https://api.example.com/login 
  -H "Content-Type: application/json" 
  -d '{"username":"test","password":"pass"}'

性能测试

# 测量请求总耗时
curl -w "Total time: %{time_total}s\n" https://example.com

# 获取详细时间指标
curl -w "\nDNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTransfer: %{time_starttransfer}s\nTotal: %{time_total}s\n" 
  -o /dev/null -s https://example.com

常见调试技巧

# 显示请求与响应头
curl -v https://api.example.com

# 记录完整请求追踪日志
curl --trace-ascii trace.txt https://api.example.com

# 在输出中包含响应头
curl -i https://api.example.com

常用模式

快速测试 JSON API：

curl -s https://api.github.com/users/octocat | jq '{name, bio, followers}'

带进度条下载：

curl -# -O https://example.com/large-file.zip

POST JSON 并提取字段：

curl -s -X POST https://api.example.com/login 
  -H "Content-Type: application/json" 
  -d '{"user":"test","pass":"secret"}' | jq -r '.token'

检查 URL 是否可访问：

if curl -s --head --fail https://example.com > /dev/null; then
  echo "Site is up"
else
  echo "Site is down"
fi

并行下载：

for i in {1..10}; do
  curl -O https://example.com/file$i.jpg &
done
wait

常用参数标志

• -X：指定 HTTP 方法（GET、POST、PUT、DELETE 等）
• -d：发送的数据（用于 POST/PUT）
• -H：添加自定义请求头
• -o：将响应写入指定文件
• -O：使用远程文件名保存响应
• -L：跟随 HTTP 重定向
• -i：在输出中包含响应头
• -I：仅获取响应头（HEAD 请求）
• -v：启用详细输出（含请求/响应头）
• -s：静默模式（不显示进度条）
• -S：静默模式下仍显示错误信息
• -f：HTTP 错误时不输出响应体，仅返回非零退出码
• -k：跳过 SSL 证书验证（不安全，仅限测试）
• -u：Basic Authentication 用户名密码
• -F：以 multipart/form-data 方式提交表单数据
• -b：发送 Cookie
• -c：将服务器返回的 Cookie 保存至文件
• -w：自定义输出格式（如响应时间、状态码等）

使用技巧

• 脚本中使用 -s 抑制进度条输出
• 组合使用 -sS 实现静默但保留错误提示
• 对短链接或重定向场景使用 -L
• 调试时添加 -v 查看完整通信过程
• 使用 jq 工具解析和格式化 JSON 响应
• 将常用请求保存为 shell alias 或独立脚本复用
• 对复杂可复用请求使用 --config 从配置文件加载参数

文档参考

官方文档：https://curl.se/docs/
手册页：man curl
HTTP 方法说明：https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods