本文详解如何修复 aws workdocs api 上传文件时出现的“socket connection idle timeout”错误，重点纠正 curl 配置误区，推荐使用 guzzle 客户端配合流式上传，并提供安全、稳定、可复用的 php 实现方案。
本文详解如何修复 aws workdocs api 上传文件时出现的“socket connection idle timeout”错误，重点纠正 curl 配置误区，推荐使用 guzzle 客户端配合流式上传，并提供安全、稳定、可复用的 php 实现方案。
在使用 AWS WorkDocs PHP SDK 上传文档时，即使仅上传 1KB 的小文件，仍可能遇到如下错误：
Your socket connection to the server was not read from or written to within the timeout period. Idle connections will be closed.
该错误并非由文件大小引起，而是源于底层 HTTP 客户端（尤其是原生 cURL）在配置不当情况下导致连接空闲超时被服务端强制关闭。你提供的代码中存在多个关键问题：
- ❌
CURLOPT_PUT => true与CURLOPT_POSTFIELDS混用冲突：CURLOPT_PUT表示启用 PUT 方法，但同时设置CURLOPT_POSTFIELDS会触发 cURL 内部逻辑异常，可能导致请求体未正确发送或连接挂起； - ❌
CURLOPT_INFILE+CURLOPT_INFILESIZE虽可用于流式上传，但需确保CURLOPT_UPLOAD => true（而非CURLOPT_PUT），且必须显式调用curl_setopt($ch, CURLOPT_UPLOAD, true)； - ❌ 强制禁用 SSL 验证（
CURLOPT_SSL_VERIFYPEER=false）仅是临时绕过手段，存在安全风险，不应作为生产方案； - ❌ 手动构造 cURL 请求易出错，缺乏自动重试、超时控制、错误上下文等健壮性保障。
✅ 正确做法是：弃用裸 cURL，改用 AWS 官方推荐的 Guzzle HTTP 客户端，它天然支持流式上传、自动处理连接复用、内置超时与重试策略，并能优雅处理大文件和长连接场景。
以下是经过验证的完整、安全、可直接运行的解决方案：
use GuzzleHttp\Client as GuzzleClient;
// 假设 $uploadUrl 来自 initiateDocumentVersionUpload 响应
$filePath = 'C:/wamp64/www/test_aws/test-file.txt';
// ✅ 推荐：使用 Guzzle 流式上传（无需加载整个文件到内存）
$body = fopen($filePath, 'r');
if (!$body) {
throw new RuntimeException("Failed to open file: {$filePath}");
}
// 创建 Guzzle 客户端 —— 生产环境请移除 verify => false，改用系统 CA 或指定证书路径
$guzzle = new GuzzleClient([
'timeout' => 30,
'connect_timeout' => 10,
'verify' => true, // ? 生产环境务必启用 SSL 验证！
]);
try {
$response = $guzzle->put($uploadUrl, [
'headers' => [
'Content-Type' => 'application/octet-stream',
'x-amz-server-side-encryption' => 'AES256',
],
'body' => $body, // 直接传入资源句柄，Guzzle 自动流式传输
]);
fclose($body);
if ($response->getStatusCode() === 200) {
echo "✅ 文件上传成功！\n";
} else {
echo "⚠️ 上传失败，HTTP 状态码：{$response->getStatusCode()}\n";
}
} catch (\GuzzleHttp\Exception\RequestException $e) {
fclose($body);
$msg = $e->getMessage();
if ($e->hasResponse()) {
$msg .= ' | Response: ' . (string)$e->getResponse()->getBody();
}
echo "❌ 请求异常：{$msg}\n";
}? 关键注意事项：
-
SSL 验证不可省略：开发阶段若遇证书问题，应通过
composer require symfony/http-client+ca-bundle或配置openssl.cafile解决，而非全局禁用verify => false； -
超时参数建议：
timeout=30（总超时）、connect_timeout=10（连接建立超时）可适配大多数网络环境；对于大文件，可按filesize / 100000（约每 MB 1 秒）动态调整； -
资源释放：务必在
try/catch中fclose($body)，避免文件句柄泄漏； -
错误处理：Guzzle 会抛出
RequestException，需捕获并检查响应体，WorkDocs 上传失败时通常返回带x-amzn-ErrorType头的 JSON 错误信息； - 替代方案（如必须用 cURL）：仅当无法引入 Guzzle 时，应严格使用以下最小安全配置：
$ch = curl_init($uploadUrl); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 30); curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); // 启用证书验证 curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_UPLOAD, true); curl_setopt($ch, CURLOPT_INFILE, $fileHandle); curl_setopt($ch, CURLOPT_INFILESIZE, filesize($filePath));
综上，根本解法不是调大超时，而是选用语义清晰、行为可靠的 HTTP 客户端。Guzzle 不仅解决了空闲连接超时问题，还显著提升了代码可维护性与安全性。遵循上述实践，即可稳定完成 WorkDocs 文档上传任务。
