Claude API调用需分层设超时：cURL连接超时3–5秒、传输超时30–60秒，PHP脚本总执行时间设45–75秒并同步调整Nginx fastcgi_read_timeout，禁用无限超时，配合低速限制与错误检查。
PHP 8.2 调用 Claude 接口时，超时时间不能统一设成某个固定值，得按请求场景分层设置，并留出合理余量。Claude 官方 API（通过 Anthropic 的 HTTPS endpoint）属于典型的外部高延迟服务——尤其在生成长文本、流式响应或模型负载高时，首字节延迟（TTFB）可能达 2～5 秒，完整响应常需 3～15 秒不等。盲目设短会频繁失败，设太长又拖累用户体验和并发能力。
推荐分层配置如下：
cURL 连接与传输超时（最核心）
这是直接影响 Claude 请求成败的第一道防线，必须显式设置，不可依赖默认值（cURL 默认 CURLOPT_TIMEOUT 是 0，即无限等待）： - CURLOPT_CONNECTTIMEOUT_MS：设为 3000～5000 毫秒（3～5 秒）。覆盖 DNS 解析、TCP 握手、TLS 协商。网络波动时 5 秒足够判断连接是否可行。 - CURLOPT_TIMEOUT_MS：设为 30000～60000 毫秒（30～60 秒）。涵盖整个请求周期：发请求头/体、等待 Claude 返回首字节、接收全部响应内容。普通问答建议 30 秒；若启用 stream=true 或处理长上下文，建议 45～60 秒。 - 同时开启低速限制防挂起：`curl_setopt($ch, CURLOPT_LOW_SPEED_LIMIT, 1);`
`curl_setopt($ch, CURLOPT_LOW_SPEED_TIME, 30);` 表示连续 30 秒下载速率低于 1 字节/秒就中断，避免卡在慢响应里。
PHP 脚本总执行时间兜底
防止 cURL 超时失效或出现其他阻塞（如日志写入、中间件逻辑）导致脚本滞留： - Web 环境下，max_execution_time 建议设为 45～75 秒（比 cURL TIMEOUT 多 10～15 秒缓冲）； - 可在脚本开头调用：`set_time_limit(60);` 注意：该值会被 Nginx 的 `fastcgi_read_timeout` 或 Apache 的 `Timeout` 指令覆盖，必须同步检查 Web 服务器配置。
流上下文与错误容错补充
若部分逻辑使用 `file_get_contents()` 或 `stream_socket_client()` 调用 Claude，需额外设置： - `stream_context_set_default(['http' => ['timeout' => 45]]);` 单位是秒，不支持毫秒，适合简单场景； - 总是检查 cURL 错误：`if (curl_errno($ch)) { throw new RuntimeException(curl_error($ch)); }` 避免超时后静默失败； - 对非幂等操作（如含 side-effect 的 `/messages` 创建），建议加重试机制（最多 2 次），但需用 `retry-after` 响应头或指数退避，而非简单循环。
生产环境特别注意
- 不要设 `set_time_limit(0)` 或 `CURLOPT_TIMEOUT = 0` —— Web 服务中极易引发连接堆积； - Nginx 必须匹配：`fastcgi_read_timeout 60;`（与 PHP 层 TIMEOUT 对齐）； - 若用 Guzzle，其 `timeout` 选项对应 cURL 的 `CURLOPT_TIMEOUT_MS`，`connect_timeout` 对应 `CURLOPT_CONNECTTIMEOUT_MS`，配置逻辑一致； - 日志中重点观察 `cURL error 28`（operation timed out）和 `504 Gateway Timeout`，前者是 PHP 层超时，后者说明请求根本没到 PHP，需查反向代理或网络链路。实际调试时，可用 curl -v --connect-timeout 5 --max-time 45 https://api.anthropic.com/v1/messages 模拟验证端到端耗时。稳定上线前，在不同网络条件下压测 100 次，统计 95 分位响应时间，再把超时值设为其 1.5 倍较稳妥。
