本文详解如何修复 aws workdocs php sdk 上传文件时出现的 “socket connection idle timeout” 错误，重点解决因 ssl 验证、curl 配置不当及 http 方法误用导致的连接中断问题，并提供安全、稳定、符合 aws 最佳实践的上传实现。
本文详解如何修复 aws workdocs php sdk 上传文件时出现的 “socket connection idle timeout” 错误，重点解决因 ssl 验证、curl 配置不当及 http 方法误用导致的连接中断问题，并提供安全、稳定、符合 aws 最佳实践的上传实现。
在使用 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 或 Guzzle）与 WorkDocs 预签名上传 URL 交互时的配置缺陷。原始代码存在多个关键问题：
- ❌ 错误混用
CURLOPT_PUT与CURLOPT_POSTFIELDS：PUT请求不应设置CURLOPT_POSTFIELDS（它隐式触发POST行为），且会干扰流式上传； - ❌ 手动管理 cURL SSL 选项（如
CURLOPT_SSL_VERIFYHOST/CURLOPT_SSL_VERIFYPEER = false）属于临时规避，易引发安全风险且不兼容现代 SDK； - ❌ 未正确传递文件流体（
fopen()句柄需直接作为body，而非通过CURLOPT_INFILE+CURLOPT_INFILESIZE组合）； - ❌ 缺少必要的请求头校验与响应处理逻辑。
✅ 推荐方案：使用 AWS SDK v3 内置的 Guzzle HTTP 客户端，并严格遵循官方上传流程
以下是经过验证、生产就绪的完整实现（基于 aws/aws-sdk-php v3.290+）：
use Aws\WorkDocs\WorkDocsClient;
use GuzzleHttp\Client as GuzzleClient;
// 1. 初始化 WorkDocs 客户端（确保凭证与区域配置正确）
$client = new WorkDocsClient([
'version' => 'latest',
'region' => 'us-east-1', // 替换为你的 WorkDocs 区域
'credentials' => [
'key' => 'YOUR_ACCESS_KEY',
'secret' => 'YOUR_SECRET_KEY',
],
]);
// 2. 发起上传初始化请求，获取预签名 URL
$result = $client->initiateDocumentVersionUpload([
'Name' => 'test-file.txt',
'ParentFolderId' => 'fld-xxxxxxxxxxxxxxxxx', // 替换为真实父文件夹 ID
]);
$uploadUrl = $result->get('UploadMetadata')['UploadUrl'];
// 3. 使用 Guzzle 直接执行 PUT 上传（推荐方式）
$filePath = 'C:/wamp64/www/test_aws/test-file.txt';
$body = fopen($filePath, 'r');
// ✅ 正确配置：禁用 SSL 验证仅用于开发环境；生产务必启用证书验证
$guzzle = new GuzzleClient([
'verify' => true, // 生产环境必须设为 true（默认值），或指定 CA bundle 路径
'timeout' => 300, // 显式设置足够长的超时（WorkDocs 上传可能受网络影响）
]);
try {
$response = $guzzle->put($uploadUrl, [
'headers' => [
'Content-Type' => 'application/octet-stream',
'x-amz-server-side-encryption' => 'AES256',
],
'body' => $body,
]);
fclose($body);
if ($response->getStatusCode() === 200) {
echo "✅ 文件上传成功！\n";
} else {
throw new Exception("HTTP {$response->getStatusCode()}: " . $response->getReasonPhrase());
}
} catch (\GuzzleHttp\Exception\RequestException $e) {
fclose($body);
error_log("上传失败: " . $e->getMessage());
throw $e;
}
? 关键注意事项：
-
SSL 验证必须分级管控：开发测试可临时设
'verify' => false，但生产环境必须启用证书验证（'verify' => true或指向系统 CA bundle，如/etc/ssl/certs/ca-certificates.crt），否则违反安全合规要求； -
超时时间不可省略：WorkDocs 上传虽快，但网络抖动或代理延迟可能导致默认 30 秒超时触发。建议显式设置
'timeout' => 300（5 分钟）； -
禁止手动构造 PUT 请求：避免混合使用 cURL 低级选项（如
CURLOPT_PUT+CURLOPT_POSTFIELDS），这极易破坏 HTTP 流语义，导致连接空闲超时； -
资源及时释放：务必在上传后调用
fclose($body)，防止文件句柄泄漏； -
响应状态校验必不可少：仅检查
curl_exec()返回值不足以判断成功，必须验证 HTTP 状态码（200 表示上传完成）。
? 进阶提示：若需支持大文件分块上传或断点续传，应改用 completeDocumentVersionUpload 配合 updateDocumentVersion 流程，而非依赖单次 initiateDocumentVersionUpload。
遵循以上方案，即可彻底规避 “idle connection timeout” 错误，实现稳定、安全、符合 AWS 规范的 WorkDocs 文档上传。
