AWS SDK for iOS 中 AWSS3TransferUtility 上传 GIF 文件的问题分析

2025-07-09 05:20:31作者：平淮齐Percy

问题背景

在使用 AWS SDK for iOS 开发过程中，开发者遇到了一个关于 AWSS3TransferUtility 上传 GIF 文件的特殊问题。当尝试从相册中选择 GIF 文件并通过 URL 上传时，上传操作会静默失败，既不会调用完成回调，也不会返回任何错误信息。

问题现象

开发者描述的具体现象包括：

从相册选择 GIF 文件后，使用 AWSS3TransferUtility 的 uploadFile 方法上传
上传操作的完成回调没有被调用
控制台出现 "SWIFT TASK CONTINUATION MISUSE" 错误
同样的代码上传视频文件（如 MP4）则工作正常

技术分析

经过深入分析，这个问题实际上涉及多个层面的技术细节：

1. 上传流程的验证阶段

AWSS3TransferUtility 在上传文件前会执行一系列验证步骤，包括但不限于：

检查文件是否存在
验证文件可读性
检查网络连接状态
验证 AWS 凭证有效性

这些验证发生在实际网络传输之前，如果任何一项验证失败，上传任务甚至不会开始。

2. 回调机制的设计缺陷

当前 SDK 的设计存在一个不太直观的行为：完成回调（completionHandler）只会在上传任务实际开始并完成后触发。如果验证阶段失败，回调根本不会被调用，这导致了开发者看到的"静默失败"现象。

3. 相册 GIF 文件的特殊处理

从 iOS 相册中选择的 GIF 文件 URL 可能有特殊的访问限制或格式要求。开发者发现通过先将 GIF 转换为 Data 再使用 uploadData 方法可以正常工作，这暗示了直接使用 URL 上传可能存在访问权限或格式兼容性问题。

解决方案

针对这个问题，推荐以下解决方案：

1. 检查上传任务返回的 AWSTask 对象

AWSS3TransferUtility 的 uploadFile 方法会返回一个 AWSTask 对象，即使验证失败，这个对象的 error 属性也会包含错误信息：

let uploadTask = transferUtility.uploadFile(fileURL, 
                                          bucket: bucketName,
                                          key: objectKey,
                                          contentType: "image/gif",
                                          expression: expression) { task, error in
    // 这个回调只在上传任务实际执行后才会被调用
}

// 检查上传任务是否因验证失败而无法开始
if let error = uploadTask.error {
    // 处理验证阶段的错误
}

2. 使用 uploadData 替代方案

如果遇到相册文件 URL 的特殊问题，可以先将文件读取为 Data 再上传：

do {
    let gifData = try Data(contentsOf: gifURL)
    transferUtility.uploadData(gifData,
                             bucket: bucketName,
                             key: objectKey,
                             contentType: "image/gif",
                             expression: expression) { task, error in
        // 处理上传结果
    }
} catch {
    // 处理文件读取错误
}

3. 实现更健壮的错误处理

结合上述两种方法，可以构建更全面的错误处理机制：

func uploadGIF(from url: URL) async throws {
    return try await withCheckedThrowingContinuation { continuation in
        // 先尝试直接上传
        let uploadTask = transferUtility.uploadFile(url, ...) { task, error in
            // 处理上传结果
        }
        
        // 检查是否因验证失败而无法上传
        if let error = uploadTask.error {
            // 验证失败，尝试使用 Data 方式上传
            do {
                let gifData = try Data(contentsOf: url)
                transferUtility.uploadData(gifData, ...) { task, error in
                    // 处理上传结果
                }
            } catch {
                // 处理所有错误情况
            }
        }
    }
}