AWS Amplify Storage 文件上传问题分析与解决方案

问题背景

在使用 AWS Amplify Storage 进行文件上传时，开发者可能会遇到 Multipart 上传失败的问题，错误信息显示为"Invalid parameter for ComplteMultipartUpload API: [object Object]"。这个问题主要出现在上传较大文件（通常超过5MB）时，因为 Amplify 会自动切换到分段上传模式。

问题现象

当尝试上传 APK、PDF 等较大文件时，开发者会遇到以下情况：

1. 上传过程看似正常完成
2. 但在最后阶段抛出错误
3. 控制台显示 Multipart 上传参数无效的错误
4. 有时第一次上传失败，但第二次尝试却能成功

根本原因

经过深入分析，发现问题的核心在于 S3 存储桶的 CORS 配置不完整。具体表现为：

1. 分段上传过程中，服务器返回的 ETag 头部没有被正确暴露
2. Amplify SDK 需要 ETag 来构建完整的 Multipart 上传请求
3. 由于 CORS 配置中缺少必要的 ExposeHeaders，导致客户端无法获取 ETag 信息
4. 最终导致 CompleteMultipartUpload API 调用失败

解决方案

要解决这个问题，需要为 S3 存储桶配置正确的 CORS 规则。以下是推荐的配置示例：

[
    {
        "AllowedHeaders": ["*"],
        "AllowedMethods": ["POST", "GET", "HEAD", "DELETE", "PUT"],
        "AllowedOrigins": ["*"],
        "ExposeHeaders": [
            "ETag",
            "x-amz-server-side-encryption",
            "x-amz-request-id",
            "x-amz-id-2"
        ],
        "MaxAgeSeconds": 3000
    }
]

关键配置点：

1. 必须包含 ETag 在 ExposeHeaders 中
2. 允许必要的 HTTP 方法（PUT、POST 等）
3. 根据实际需求设置 AllowedOrigins，生产环境不建议使用 "*"

最佳实践

1. 对于生产环境，应该限制 AllowedOrigins 为具体的域名
2. 根据实际需求调整 MaxAgeSeconds 值
3. 如果使用 Amplify CLI 创建存储桶，这些配置通常会自动设置
4. 对于手动创建的存储桶，务必检查 CORS 配置
5. 对于敏感操作，建议在存储桶策略中实施更精细的权限控制

技术原理

分段上传是 AWS S3 处理大文件的机制，它将文件分成多个部分分别上传，最后通过 CompleteMultipartUpload API 合并。整个过程需要：

1. 初始化上传（获取 UploadId）
2. 上传各个部分（每个部分需要记录 ETag）
3. 完成上传（提供所有部分的 ETag）
4. 验证上传结果（通过 GET/HEAD 请求）

如果客户端无法获取 ETag，就无法正确完成第三步，导致上传失败。

总结

AWS Amplify Storage 的分段上传功能依赖于正确的 S3 存储桶配置。开发者在使用时，特别是对于手动配置的存储桶，务必检查 CORS 设置，确保包含必要的暴露头部。这个问题看似复杂，但解决方案其实很简单，只需要几分钟的配置调整就能彻底解决。