cURL 超时详解：设置、修复与示例

默认情况下，如果服务器没有响应，cURL 命令可能会无限期挂起，这是因为除非手动设置，否则整个操作没有超时限制；实际使用中，一旦 cURL 请求挂起，可能会导致整个脚本停滞。

为确保可靠性，请始终设置合适的超时参数，避免 cURL 无限期等待：一旦操作超过设定时限，便会立即终止并返回错误，而不是持续卡住。

cURL 超时是什么？

所谓cURL 超时，是指使用 cURL 时请求允许运行的最长时间限制。如果没有设置超时，cURL 可能会无限期等待一个永远不会到来的响应，这会导致脚本挂起、资源浪费和令人烦恼的延迟。

超时设置之所以重要，是因为它能保护您的应用程序免受不稳定服务器、网络连接不佳以及意外延迟的影响；如果请求耗时过长，cURL 会停止并报告错误，从而让您的脚本或程序能够妥善处理问题，例如重试或记录失败日志。

您可以设置多种类型的超时：用于限制连接服务器耗时的连接超时、用于限制整个操作耗时的最大时间，以及在传输速度过慢时触发的低速超时。它们各自都在确保 cURL 请求不会挂起或静默失败方面发挥作用。

cURL 超时的类型

cURL 提供了几项选项，用于控制其等待时长：

• 总超时时间（--max-time）：以秒为单位设置整个请求的最长时间，超过该时间 cURL 会中止请求并返回超时错误。
• 连接超时（--connect-timeout）：设置建立连接（DNS 查询 + 握手）所允许的最长时间，若在该时限内未能连接到服务器，cURL 会终止尝试并返回超时错误 28。
• 低速传输超时：当数据传输速度长时间低于指定速率时，中止本次传输。
• 毫秒级精度选项（libcurl）：如果您在代码中使用 libcurl（cURL 的底层库），可以使用诸如 CURLOPT_TIMEOUT_MS 和 CURLOPT_CONNECTTIMEOUT_MS 这样的选项，以毫秒精度设置超时时间，这对需要精确控制超时值的应用程序非常实用。

cURL 的默认超时行为

如果未设置任何超时，将会出现以下情况：

• 没有总体限制

默认情况下，cURL 未设置最大时间限制，可能会无限期等待操作完成。除非手动指定，否则不会强制施加 cURL 最大时间限制。

• cURL 默认连接超时

cURL 为连接阶段内置了约 300 秒（5 分钟）的超时时间，这一默认值相当高，因此通常会通过自定义 --connect-timeout 来调低。

• 无低速传输中断机制

低速中止功能默认处于关闭状态，因此即使传输速度极慢或停滞，也会继续进行。

• 总结

依赖默认设置存在风险，因为 cURL 请求可能永久挂起并阻塞您的程序。更稳妥的做法是明确设置 cURL 连接超时和总超时时间，从而自行掌控 cURL 的等待时长。

如何在 cURL 中设置超时

执行 cURL 命令时，可通过以下选项配置超时：

总操作超时：--max-time

为请求的总耗时设置上限（以秒为单位的最大时间），若传输超过该时间，cURL 将终止请求。以下示例将请求时长上限设为 30 秒。

curl --max-time 30 https://example.com

连接超时：--connect-timeout

限制 cURL 等待连接主机（包括 DNS 解析）的时长，以下示例会使 cURL 在 5 秒内无法连接时放弃尝试。

curl --connect-timeout 5 https://example.com 

低速传输超时：--speed-limit 与 --speed-time

指示 cURL 中止速度过慢的传输，以下示例会在下载速度连续 15 秒低于每秒 1000 字节时停止下载。

curl --speed-limit 1000 --speed-time 15 https://example.com/file.zip

libcurl 的超时选项

在 libcurl 中，也存在与上述选项对应的设置，例如：

• CURLOPT_TIMEOUT 用于设置总超时时间（默认值为 0，表示不限制）
• CURLOPT_CONNECTTIMEOUT 用于设置连接超时时间（默认值为 300 秒）

此外还有毫秒精度的版本（如 CURLOPT_TIMEOUT_MS 等），以及用于中止低速传输的低速阈值选项（CURLOPT_LOW_SPEED_LIMIT 和 CURLOPT_LOW_SPEED_TIME）。

常见 cURL 超时错误及修复方法

错误 28：操作超时

错误 28 是 cURL 表示超时的错误代码，表明传输未能在指定超时时间内完成。错误信息中可能出现“...0 bytes received”字样，意味着在超时发生前未从服务器接收到任何数据。要解决此问题，可适当调高过低的超时相关数值，或排查网络与服务器是否存在延迟问题。

“Operation timed out after X ms with 0 bytes received”

这是一条常见的提示信息，表示 cURL 已达到最大时间限制（例如 --max-time），或是在接收到任何数据之前连接超时已到期。若频繁出现此情况，可能意味着存在 DNS 解析问题、服务器无响应，或网络连接存在故障。

使用 -v 与 --trace-time 调试超时问题

要排查 cURL 请求究竟卡在哪个环节，可使用 -v 标志开启详细输出模式，查看连接的每个阶段，包括 DNS 解析和 SSL 握手过程。再添加 --trace-time 为日志的每一行加上时间戳。结合使用这两项选项，可以帮助您判断延迟究竟发生在 cURL 连接超时阶段、数据传输阶段，还是整个操作流程中的其他环节。

如何选择合适的超时值

选择合适的数值取决于您所发起请求的类型以及网络状况，并没有放之四海而皆准的标准，但以下通用指南可帮助您更有效地设置超时。

• API：建议使用较短的连接超时（2–5 秒）和最大时间 10–30 秒。API 请求（尤其是搭配 代理 使用时）通常响应很快，若出现长时间延迟，往往意味着存在问题。
• 类浏览器网页请求：建议使用 5–10 秒的连接超时和 30–60 秒的最大时间，以适应较大的 HTML 响应或重定向情况。
• 大文件下载：可以将最大时间设置得更高，例如 300–900 秒，但连接超时仍应保持较短（5–10 秒）。此外，建议结合 --speed-limit 和 --speed-time 启用低速中止功能，以停止停滞的传输。
• 命令行工具与脚本：务必明确设置超时，以防脚本挂起，一组较为稳妥的默认值是 --connect-timeout 5 搭配 --max-time 30。

选择数值时，请权衡以下三项因素：

• 超时时长：设置过短可能导致请求过早失败，设置过长则可能阻塞您的应用程序。
• 重试逻辑：若您会对失败的请求进行重试，较短的超时时间效果更好。
• 网络状况：若网络不稳定，可适当延长超时时间，以减少误判为超时的情况。

需要处理身份验证类 API？可参考我们关于 cURL bearer tokens 的指南，了解如何在配置超时的同时处理基于令牌的身份验证。