AWS SDK for JavaScript v3 上传文件到 S3 的常见问题与解决方案

在基于浏览器的前端应用中使用 AWS SDK for JavaScript v3 上传文件到 S3 存储桶时，开发者可能会遇到 net::ERR_H2_OR_QUIC_REQUIRED 错误。这个错误通常与 HTTP/2 或 QUIC 协议相关，表明浏览器无法建立符合要求的连接。

问题现象

当开发者尝试使用 @aws-sdk/client-s3 的 PutObjectCommand 进行文件上传时，在 Chrome 或其他基于 Chromium 的浏览器中可能会遇到 net::ERR_H2_OR_QUIC_REQUIRED 错误。这个错误表明目标服务器要求使用 HTTP/2 或 QUIC 协议，但浏览器无法建立符合要求的连接。

根本原因分析

这个错误通常由以下几个因素导致：

1. 协议兼容性问题：AWS S3 服务端可能配置了严格的协议要求，而客户端环境无法满足
2. 网络中间件干扰：安全防护系统或网络管理工具可能拦截或修改了 HTTP 请求
3. 浏览器限制：某些浏览器版本或配置可能对 HTTP/2 或 QUIC 支持不完全
4. SDK 使用方式：直接使用低级别的 PutObjectCommand 可能不如高级 API 稳定

解决方案

方案一：使用 XMLHttpRequest 替代 Fetch API

对于需要进度跟踪的上传场景，可以考虑使用传统的 XMLHttpRequest 方式：

const xhr = new XMLHttpRequest();
xhr.open("PUT", signedUrl);
xhr.setRequestHeader("Content-Type", contentType);

xhr.upload.onprogress = (event) => {
  if (event.lengthComputable) {
    const percentComplete = (event.loaded / event.total) * 100;
    handleProgress(percentComplete);
  }
};

xhr.onload = () => {
  if (xhr.status === 200) {
    // 处理成功情况
  } else {
    // 处理失败情况
  }
};

xhr.send(file);

这种方法的优势在于：

• 更好的浏览器兼容性
• 内置的进度事件支持
• 避免现代协议要求的限制

方案二：使用 @aws-sdk/lib-storage 的高级 Upload 接口

AWS SDK 提供了专门为浏览器环境优化的上传工具：

import { Upload } from "@aws-sdk/lib-storage";

const upload = new Upload({
  client: s3Client,
  params: {
    Bucket: 'bucket-name',
    Key: 'file-name',
    Body: file,
    ContentType: file.type
  }
});

upload.on('httpUploadProgress', (progress) => {
  console.log(progress);
});

await upload.done();

这个方案的优势包括：

• 内置重试机制
• 自动处理大文件分块上传
• 更好的错误恢复能力
• 内置进度事件

方案三：检查并排除网络干扰

如果问题持续存在，可以检查以下方面：

1. 关闭可能干扰网络连接的软件（如网络调试工具等）
2. 尝试不同的网络环境（如切换 WiFi 或使用移动热点）
3. 检查浏览器扩展是否影响了网络请求
4. 确保操作系统和浏览器是最新版本

最佳实践建议

1. 优先使用高级 API：对于浏览器环境，@aws-sdk/lib-storage 的 Upload 类通常是更好的选择，它专门为浏览器环境优化，处理了各种边界情况。

2. 考虑使用预签名 URL：对于安全性要求较高的场景，可以在服务器端生成预签名 URL，然后让前端直接上传到 S3，避免在前端暴露长期有效的凭证。

3. 实现完善的错误处理：无论采用哪种上传方式，都应该实现全面的错误处理和重试逻辑，特别是对于不稳定的移动网络环境。

4. 监控上传质量：在生产环境中，建议收集上传成功率、速度等指标，及时发现潜在问题。

通过理解这些技术细节和解决方案，开发者可以更可靠地在浏览器环境中实现文件上传到 AWS S3 的功能，避免常见的协议和网络相关问题。