调试和排错是 cURL 的重要应用场景。掌握调试技巧能快速定位网络请求问题、API 故障和性能瓶颈。
基本调试参数
# 显示详细信息（最常用） curl -v https://api.example.com # 仅显示响应头 curl -I https://api.example.com # 显示响应头和内容 curl -i https://api.example.com # 静默模式（不显示进度） curl -s https://api.example.com # 显示错误信息 curl -S https://api.example.com
详细输出模式
# -v 显示完整的请求和响应过程 curl -v https://api.example.com/users # 输出说明： # > 表示发送的请求行和请求头 # < 表示接收的响应头 # * 表示连接和 SSL 握手信息 # 更详细的调试信息 curl --trace-ascii debug.log https://api.example.com # 十六进制格式输出 curl --trace debug.hex https://api.example.com
响应时间分析
# 显示传输统计信息 curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \ -o /dev/null -s https://api.example.com # 完整的性能分析 curl -w "DNS解析: %{time_namelookup}s\nTCP连接: %{time_connect}s\nSSL握手: %{time_appconnect}s\n首字节: %{time_starttransfer}s\n总时间: %{time_total}s\n下载大小: %{size_download}bytes\n下载速度: %{speed_download}bytes/s\n" \ -o /dev/null -s https://api.example.com # 输出到文件 curl -w "@curl-format.txt" -o /dev/null -s https://api.example.com
常用调试变量
| 变量 | 说明 |
|---|---|
time_namelookup | DNS 解析时间 |
time_connect | TCP 连接时间 |
time_appconnect | SSL/SSH 握手时间 |
time_starttransfer | 首字节时间（TTFB） |
time_total | 总时间 |
size_download | 下载大小 |
speed_download | 下载速度 |
http_code | HTTP 状态码 |
错误排查技巧
# 1. 检查 HTTP 状态码 curl -w "\nHTTP Status: %{http_code}\n" -o /dev/null -s https://api.example.com # 2. 检查重定向链 curl -L -v https://example.com 2>&1 | grep -E "(< HTTP|< Location)" # 3. 检查 SSL 证书 curl -v https://api.example.com 2>&1 | grep -A 10 "SSL connection" # 4. 忽略 SSL 证书验证（仅测试用） curl -k https://self-signed.badssl.com # 5. 设置超时时间 curl --connect-timeout 5 --max-time 10 https://api.example.com # 6. 重试机制 curl --retry 3 --retry-delay 2 https://api.example.com
网络问题诊断
# 测试连接性 curl -v telnet://example.com:80 # 检查代理设置 curl -v --proxy http://proxy.example.com:8080 https://api.example.com # 指定 DNS 服务器 curl --dns-servers 8.8.8.8 https://api.example.com # 强制使用 IPv4 curl -4 https://api.example.com # 强制使用 IPv6 curl -6 https://api.example.com # 查看路由追踪 curl -v --trace-time https://api.example.com
完整调试脚本
#!/bin/bash # API 调试脚本 URL="https://api.example.com/users" TOKEN="your_token_here" echo "========== 请求信息 ==========" echo "URL: $URL" echo "Time: $(date)" echo "" echo "========== 详细请求过程 ==========" curl -v -X GET "$URL" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ 2>&1 echo "" echo "========== 性能指标 ==========" curl -w "DNS解析: %{time_namelookup}s\nTCP连接: %{time_connect}s\nSSL握手: %{time_appconnect}s\n首字节: %{time_starttransfer}s\n总时间: %{time_total}s\nHTTP状态: %{http_code}\n" \ -o /dev/null -s "$URL" \ -H "Authorization: Bearer $TOKEN" echo "" echo "========== 响应内容 ==========" curl -s "$URL" -H "Authorization: Bearer $TOKEN" | jq '.'
常见问题排查清单
# 1. 连接超时 curl --connect-timeout 10 https://api.example.com # 2. 读取超时 curl --max-time 30 https://api.example.com # 3. DNS 解析问题 curl --resolve example.com:443:192.168.1.100 https://example.com # 4. 证书问题 curl --cacert /path/to/ca.crt https://api.example.com # 5. 编码问题 curl -H "Accept-Charset: UTF-8" https://api.example.com # 6. 压缩传输 curl --compressed https://api.example.com
日志记录
# 保存完整调试日志 curl -v https://api.example.com > response.txt 2>&1 # 分别保存请求和响应 curl -v https://api.example.com \ --trace-ascii request-trace.txt \ -o response-body.txt # 时间戳日志 curl --trace-time -v https://api.example.com 2>&1 | tee debug.log