如何用 curl 排查 HTTP 接口问题？

简化版

curl 是命令行下发 HTTP 请求、排查接口问题的利器。最常用几招：curl -v URL 看完整请求/响应过程（DNS、TCP、TLS、请求头、状态码、响应头）；curl -I URL 只看响应头和状态码（HEAD 请求）；curl -w 打印各阶段耗时（定位慢在 DNS 还是连接还是服务端）；curl --resolve 绕过 DNS 直连指定 IP（排查是不是解析问题）。它能把「接口报错/超时/慢」拆解成每一层分别发生了什么，比在浏览器里瞎点精准得多。

详细版

核心选项：

选项	作用
`-v`	verbose，打印完整交互过程（排查主力）
`-I`	只发 HEAD，只看响应头 + 状态码
`-i`	响应里包含响应头（连同 body 一起显示）
`-L`	自动跟随重定向（3xx）
`-o file` / `-O`	保存响应到文件
`-s`	静默（不显示进度条，脚本常用）
`-w '...'`	请求后按格式输出统计信息（各阶段耗时）
`-x proxy`	走代理
`--resolve host:port:IP`	强制把域名解析到指定 IP（绕过 DNS）
`-k`	跳过 TLS 证书校验（排查证书问题时临时用）
`-H`	自定义请求头；`-d` 发 POST 数据；`-X` 指定方法

① 看全过程：curl -v https://example.com，逐段看 DNS→连接→TLS→请求→响应。

② 只看状态和头：curl -I https://example.com。

③ 看各阶段耗时（定位慢在哪）：

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

④ 绕过 DNS 直连某 IP（排查是不是 DNS/负载均衡问题）：

curl -v --resolve example.com:443:1.2.3.4 https://example.com

完整版教学

一、curl 为什么是接口排查神器

排查 HTTP 接口问题，浏览器有诸多干扰：缓存、Cookie、插件、CORS、JS 逻辑……看到的不一定是「服务器真实返回」。而 curl 是纯粹的 HTTP 客户端，你发什么它就发什么、服务器回什么它就显示什么，干净、可控、可脚本化。它能把「接口不通/报错/慢」这种笼统现象，拆成DNS 解析、TCP 连接、TLS 握手、发送请求、接收响应每一步分别发生了什么，从而精确定位。这也是为什么后端/运维排查接口，第一反应就是 curl -v。

二、-v 是主力：读懂一次请求的全过程

curl -v（verbose）会把整个交互过程打印出来，学会读这几段就掌握了精髓：

* Trying 1.2.3.4:443...                    ← ① DNS 已解析出 IP，正在建 TCP 连接
* Connected to example.com (1.2.3.4)       ← ② TCP 连接成功
* TLS handshake ... SSL certificate verify ok  ← ③ TLS 握手 + 证书校验
> GET / HTTP/1.1                            ← ④ > 是【发出】的请求行和请求头
> Host: example.com
>
< HTTP/1.1 200 OK                           ← ⑤ < 是【收到】的响应状态和响应头
< Content-Type: text/html
<
（响应体）

关键符号：* 是 curl 的过程说明，> 是发出的请求，< 是收到的响应。顺着看下来，哪一步出错就卡在哪一步：

卡在 Trying... 半天没 Connected → TCP 连不上（防火墙/端口/服务，对应超时）。
Connected 后 TLS 报错 → 证书问题（过期、域名不匹配、CA 不信任）。
有响应但状态码不对 → 应用层问题（看下面状态码）。

三、看状态码：接口报错的第一线索

拿到 HTTP 响应，状态码直接指明问题方向。curl -I（只发 HEAD、只看头）最快：

200：正常。
301/302：重定向。加 -L 让 curl 跟随，看最终去了哪（排查重定向循环）。
401/403：认证失败 / 无权限（缺 token、被 WAF 或防盗链拦）。
404：路径/路由不对。
400：请求格式错误（参数/body 不对）。
500：服务端程序报错（后端代码异常）。
502：网关/代理连不到后端（后端挂了/没起）。
503：服务不可用（过载、维护中）。
504：网关等后端超时（后端处理太慢）。

记忆：4xx 是客户端/请求的问题，5xx 是服务端的问题；502/504 通常是网关和后端之间出了事（连不到 / 超时）。

四、-w 看各阶段耗时：定位「慢在哪」

接口「慢」是最含糊的抱怨——慢在解析域名？建连接？TLS 握手？还是服务端处理？curl -w 能把耗时分段量化：

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

这些时间点是累计的（从请求开始算），相减得到每段耗时：

time_namelookup 大 → DNS 解析慢。
time_connect - time_namelookup 大 → TCP 建连慢（网络远/差）。
time_appconnect - time_connect 大 → TLS 握手慢。
time_starttransfer - time_appconnect 大 → 服务端处理慢（拿到首字节前的等待，多是后端逻辑/数据库慢）。

一眼就能把「慢」归因到具体某一层，这是 curl 排查性能问题的杀手锏。

五、—resolve：绕过 DNS，直击后端

一个超实用技巧：怀疑是 DNS 或负载均衡把你导到了坏的服务器时，用 --resolve 强制把域名解析到你指定的 IP，绕过真实 DNS：

curl -v --resolve example.com:443:1.2.3.4 https://example.com

这样 curl 会带着正确的 Host 头和 SNI（域名），但实际连到你指定的 1.2.3.4。用途：

验证某台后端实例是否正常：域名背后有多台服务器，用 —resolve 逐台直连，找出是哪台坏了。
区分是 DNS 问题还是服务问题：如果 —resolve 到正确 IP 就通、走 DNS 就不通，说明 DNS 解析有问题。
上线前测试：域名还没切，先用 —resolve 指到新服务器验证。

比改 hosts 文件更灵活（不影响系统、用完即弃）。

六、其他高频场景

测 POST 接口：curl -X POST -H 'Content-Type: application/json' -d '{"k":"v"}' URL。
带认证头：curl -H 'Authorization: Bearer xxx' URL。
排查证书问题：证书报错时先用 -k（跳过校验）确认「是不是只有证书的问题」——-k 能通说明服务本身好，就是证书配置问题。注意 -k 只用于排查，生产绝不能用（等于放弃 HTTPS 安全）。
看是不是被重定向坑了：curl -IL URL 跟随并显示每一跳的响应头。

七、常见误区与追问

考点	正确口径
连接阶段	DNS、TCP、TLS
请求阶段	方法、Header、Body、代理
响应阶段	状态码、重定向、耗时、证书

curl -v https://example.com
curl -I https://example.com
curl -w 'dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} total=%{time_total}\n' -o /dev/null -s https://example.com

curl -v 的价值是把 HTTP 问题拆回 DNS、TCP、TLS、请求头和响应头各阶段。

误区：curl 返回 500 就是网络问题。 500 是服务端应用响应，网络链路已经通了，重点查服务日志。
误区：只看 total time 就能定位慢在哪。 要拆 DNS、connect、TLS、TTFB、download 等阶段。
误区：浏览器能访问，curl 就一定能访问。 浏览器可能带 Cookie、代理、HTTP/2、证书信任和特殊 Header，curl 默认环境不同。
追问：如何只看响应头？ 用 curl -I 或 curl -D - 查看状态码和响应头。
追问：如何排查 TLS 证书？ 用 curl -v 看握手和证书错误，必要时结合 openssl s_client。
追问：如何复现带 Header 的请求？ 使用 -H、--data、-X、--cookie 精确构造请求。

八、加强记忆

curl 是命令行 HTTP 客户端，排查接口纯粹可控。主力 curl -v 看全过程（* 过程 / > 发出 / < 收到），顺着 DNS→TCP→TLS→请求→响应定位卡点。-I 快看状态码：4xx 客户端/请求问题、5xx 服务端问题（502 连不到后端 / 504 后端超时）。-w 把耗时分段（DNS/连接/TLS/首字节）定位「慢在哪」。--resolve host:port:IP 绕过 DNS 直连指定后端，区分 DNS 问题还是服务问题。-k 仅临时排查证书、生产禁用。

简化版

详细版