Flutter使用S3 API上传Cloudflare R2失败，求排查方案

针对使用aws_s3_upload包上传Cloudflare R2无报错但文件未存储的问题，可按以下步骤排查：

• 补全R2专属端点配置
  Cloudflare R2属于S3兼容存储，必须指定自定义端点才能将请求路由到R2服务器，你的代码中缺少该参数，默认会指向AWS S3官方地址，这是核心问题之一。
  修改uploadFile方法，添加R2端点（格式为https://<你的Cloudflare账户ID>.r2.cloudflarestorage.com）：

  await AwsS3.uploadFile(
    accessKey: "你的R2访问密钥",
    secretKey: "你的R2秘密密钥",
    file: file,
    bucket: "你的桶名",
    region: "us-east-1", // R2不验证region，但部分S3工具需填有效值，推荐用us-east-1
    endpoint: "https://<账户ID>.r2.cloudflarestorage.com",
  );
  

• 验证权限与密钥正确性

  • 确认R2 API令牌（accessKey/secretKey）拥有s3:PutObject权限，且关联的桶名称与控制台完全一致（R2桶名不区分大小写，但建议严格匹配）。
  • 登录Cloudflare控制台，检查该令牌的权限范围，确保允许对目标桶执行写入操作。

• 确认文件与上传路径有效性

  • 在uploadFile方法中添加日志，验证文件状态：

    print("待上传文件大小：${await file.length()}");
    print("目标存储路径：$path");
    

  • 检查${user.id}/${image.name}生成的路径是否包含特殊字符，避免因路径格式问题导致对象存储位置不符合预期。

• 增强调试与日志排查

  • 扩展错误捕获逻辑，打印更详细的错误信息：

    catch (e) {
      print("上传错误详情：${e.toString()}");
      throw e;
    }
    

  • 在Cloudflare控制台开启R2桶的访问日志，查看是否有上传请求到达，以及请求的状态码、错误信息，确认请求是否被正确处理。

• 调整兼容性参数

  • 将region参数从"auto"改为"us-east-1"，部分S3兼容工具对"auto"的解析存在问题，R2不验证region值，填有效值即可。
  • 确认aws_s3_upload包使用的签名版本为v4（R2仅支持v4签名），若包默认使用v2签名会导致上传失败但无明确报错。

内容的提问来源于stack exchange，提问作者Ruder Buster