cURL Error 28：连接与传输超时的排查方法

概览

cURL error 28 表示操作因为达到某项时间限制而停止。它可能发生在连接尚未建立时、等待首个响应字节时，也可能发生在下载过程中。决定增加超时或更换代理前，应先阅读完整错误，并收集请求各阶段耗时。

这个消息可能来自 curl 命令、PHP/libcurl、WordPress 或其他应用。请在失败请求实际运行的环境中测试；笔记本上的请求成功，并不能证明托管服务器具有相同线路。

哪项限制触发了 cURL error 28？

连接超时限制连接建立阶段；max-time 限制一次完整传输。图中各阶段宽度仅作示意。

curl 超时指南介绍了前三项控制。错误 28 表示超时；证书校验失败、连接被拒绝等其他情况有各自的错误。应保留实际错误码，不要把所有网络故障都当成超时。

1. 从失败的运行环境收集耗时

将 TARGET_URL 替换为目标地址。下面的 macOS/Linux 命令不会把响应正文输出到终端，而是打印累计耗时。命令没有增加重试，也不跟随重定向，以便保留第一次请求的结果。

curl --silent --show-error --output /dev/null \
  --connect-timeout 10 --max-time 30 \
  --write-out 'http=%{http_code} dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} first_byte=%{time_starttransfer} total=%{time_total}\n' \
  'TARGET_URL'

Windows 请使用 curl.exe 和 NUL。这些数值是从开始到各个节点的累计时间，不是可以直接相加的独立阶段时长。某项为零，可能表示该阶段未完成，也可能表示本次请求没有使用该阶段。应结合标准错误输出和进程退出码解读。

如果运行环境本来就需要使用代理，请按照 MIYAIP 连接教程补充协议、主机、端口和鉴权字段。只有在直连符合预期且被允许时，才进行直连对照。保持目标、请求方法和时间限制一致，才能让比较回答清楚的问题。

2. 将现象对应到具体检查项

对于代理路径，代理测速工具提供的是从 MIYAIP 测试服务器得到的测量。应将它与本地命令的结果对照；两者的发起位置不同，目标也可能不同。

3. 修复发起请求的应用，再重新测试

使用 WordPress 时，记录站点健康检查的信息，并确认失败的请求属于 REST 请求、回环请求还是外部服务调用。请托管服务管理员在 PHP 运行环境中复现完全相同的请求。如果怀疑插件冲突，应在预发布环境中对照测试，测试后恢复配置。泛泛地更换代理并不能修复损坏的回环线路。

对于定时采集器或 API 客户端，应根据预期工作负载选择时间限制。小型状态响应和大型导出需要不同的时间预算。只有确认操作本身有效、只是需要更久时，才增加时限；同时保留有限的任务总期限。

仅在失败可能是暂时性的情况下，才对只读请求重试，并限制尝试次数和等待预算。对于超时的购买、提交或其他会改变状态的请求，不要自动重新发送：即使响应丢失，远程操作也可能已经完成。收到 429 时，应遵循 Retry-After，而不是立刻轮换 IP。

在可控示例中识别超时

在本地启动随附的 network_demo.py 后，/slow 会等待两秒再响应。下面的命令刻意只允许等待 0.2 秒：

curl --noproxy '*' --max-time 0.2 'http://127.0.0.1:8766/slow'

这个本地示例以退出码 28 结束，展示传输时限到期的情况。将参数改为 --max-time 3 再运行，就能允许两秒后的响应完成。

将端点测试与自己的运行环境对照

检查连接、比较服务器端测速结果，并从应用运行环境重复相同请求。

运行本地演示

下载 network_demo.py，或将以下完整代码保存为同名文件。使用 Python 3 运行 python network_demo.py。服务仅监听 127.0.0.1:8766，使用完按 Ctrl+C 退出。

"""Local HTTP demonstration. No external requests, credentials or MIYAIP service calls."""
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import urlsplit
import json
import time


class DemoHandler(BaseHTTPRequestHandler):
    def log_message(self, *_):
        pass

    def reply(self, code, body=b"", headers=None):
        self.send_response(code)
        for key, value in (headers or {}).items():
            self.send_header(key, value)
        self.send_header("Content-Length", str(len(body)))
        try:
            self.end_headers()
            self.wfile.write(body)
        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError):
            pass

    def do_CONNECT(self):
        self.reply(407, headers={"Proxy-Authenticate": 'Basic realm="local-demo"'})

    def do_GET(self):
        path = urlsplit(self.path).path
        if path == "/redirect":
            return self.reply(302, headers={"Location": "/headers"})
        if path == "/loop":
            return self.reply(302, headers={"Location": "/loop"})
        if path == "/slow":
            time.sleep(2)
        if path in {"/headers", "/slow"}:
            payload = {"method": self.command, "headers": dict(self.headers)}
            return self.reply(200, json.dumps(payload, indent=2).encode(),
                              {"Content-Type": "application/json"})
        self.reply(404, b"Use /headers, /redirect, /loop or /slow")

    def do_POST(self):
        body = self.rfile.read(int(self.headers.get("Content-Length", "0")))
        if urlsplit(self.path).path == "/redirect307":
            return self.reply(307, headers={"Location": "/headers"})
        if urlsplit(self.path).path == "/redirect302":
            return self.reply(302, headers={"Location": "/headers"})
        payload = {"method": self.command, "headers": dict(self.headers),
                   "body": body.decode("utf-8", errors="replace")}
        self.reply(200, json.dumps(payload, indent=2).encode(),
                   {"Content-Type": "application/json"})


if __name__ == "__main__":
    print("Local demonstration: http://127.0.0.1:8766 (Ctrl+C to stop)", flush=True)
    ThreadingHTTPServer(("127.0.0.1", 8766), DemoHandler).serve_forever()

来源

• curl 官方错误码说明
• Everything curl：超时
• curl 官方手册
• MIYAIP 静态代理接入教程