Linux 用 curl 调试 HTTP 接口：先看响应再定位

摘要：用 curl 先保存响应头和正文，再按状态码、耗时、请求头逐步缩小 HTTP 接口问题。

调试接口时，先保留现场：curl -sS -D headers.txt URL -o body.txt。这样既能看到状态码和响应头，也不会把正文与诊断信息混在一起。

先做一次可回放的请求

curl -sS -D headers.txt https://api.example.test/health -o body.txt
printf 'status: '; sed -n '1p' headers.txt
cat body.txt

-sS 保留错误提示，-D 写入响应头，-o 保存正文。不要一开始就加 -f，否则错误响应正文可能被隐藏，排查线索会减少。^[1]

用状态码和耗时分流

curl -sS -o /tmp/body -w 'status=%{http_code} time=%{time_total}s size=%{size_download}\n' https://api.example.test/health

2xx 通常表示请求已成功处理；4xx 优先检查 URL、参数、认证和请求方法；5xx 则需要同时记录服务端时间与请求标识。状态码语义可查 HTTP 总览。^[2]

检查请求头与方法

curl -sS -H 'Accept: application/json' -H 'X-Request-ID: debug-001' https://api.example.test/items
curl -sS -X POST -H 'Content-Type: application/json' --data '{"name":"demo"}' https://api.example.test/items

只为验证接口契约添加头部；令牌不要写进 shell 历史或文章。需要查看实际发送内容时，可用 -v，但它会输出认证信息，日志共享前先脱敏。^[1]

遇到重定向、超时和 TLS

curl -sS -L --connect-timeout 5 --max-time 15 -w '\nfinal=%{url_effective} status=%{http_code}\n' https://api.example.test/redirect
curl -v https://api.example.test/health 2>curl-trace.log

-L 跟随重定向，超时参数限制连接与整个传输；TLS 报错不要用 -k 规避后直接下结论，应先确认证书链、主机名和系统时间。-k 只适合隔离测试，不能作为生产修复。

故障对照与回滚

回滚就是删除调试文件：rm -f headers.txt body.txt curl-trace.log /tmp/body；若命令写入了服务端数据，则按接口提供的删除或撤销 API 清理，curl 本身不会替你回滚业务副作用。

限制与测试记录

本文只验证了本机 HTTP mock 的 GET、响应头、正文和状态/耗时输出；未对真实 HTTPS、认证服务、代理或 HTTP/2 做端到端验证。线上排查还应保留时间、目标环境和 request ID。

常见问题

为什么不用 -s？ -sS 在安静输出的同时保留错误信息。

-f 什么时候用？ CI 只关心失败退出码时再用，并配合保存响应正文。

-v 会泄露什么？ 可能包含 Cookie、Authorization 等敏感信息，分享前必须脱敏。

参考资料

• [1] curl command line tool manual（curl 手册）
• [2] An overview of HTTP（MDN HTTP）

文中主要命令已在 WSL Ubuntu（24.04）实测，个别条目（未装工具/安装类命令）仅核对官方文档，未实际执行。