如何批量上传文件至 AWS S3 并获取每个文件的公开访问 URL 路径与名称

本文详解如何使用 aws java sdk 的 transfermanager 批量上传多个本地文件到 s3 存储桶，并在上传完成后准确获取每个文件的完整可访问 url 及对象键名（key），适用于构建文件托管、媒体上传等云服务场景。

在实际开发中，单文件上传后获取其 S3 URL 已属常见需求；而面对多文件批量上传（如用户选择多张图片、PDF 文档等），开发者不仅需确保全部上传成功，还需统一收集每个文件的唯一标识（Key）及其对外可访问的 URL。值得注意的是：AWS SDK for Java 不支持在单次 upload() 调用中直接返回 URL，但可通过 Upload.waitForUploadResult() 获取结构化上传结果，再结合 AmazonS3.getUrl(bucket, key) 动态构造标准 S3 对象 URL。

以下是一个健壮、可复用的批量上传实现示例（基于 AWS SDK v1.12.x）：

import com.amazonaws.AmazonServiceException;
import com.amazonaws.SdkClientException;
import com.amazonaws.auth.profile.ProfileCredentialsProvider;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.URL;
import com.amazonaws.services.s3.transfer.*;
import com.amazonaws.services.s3.transfer.model.UploadResult;

impor
t java.io.File;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CompletableFuture;

public class S3MultiFileUploader {

    public static class UploadInfo {
        public final String fileName;
        public final String objectKey;
        public final String s3Url;

        public UploadInfo(String fileName, String objectKey, String s3Url) {
            this.fileName = fileName;
            this.objectKey = objectKey;
            this.s3Url = s3Url;
        }
    }

    public static List uploadMultipleFiles(
            String region,
            String mediaBucket,
            List files,
            String baseKeyPrefix) {

        AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
                .withRegion(region)
                .withCredentials(new ProfileCredentialsProvider())
                .build();

        TransferManager tm = TransferManagerBuilder.standard()
                .withS3Client(s3Client)
                .build();

        List> futures = new ArrayList<>();

        for (int i = 0; i < files.size(); i++) {
            File file = files.get(i);
            // 推荐：为避免冲突，使用语义化 Key（如 prefix/filename-timestamp）
            String objectKey = String.format("%s/%s", baseKeyPrefix, 
                System.currentTimeMillis() + "-" + file.getName());

            CompletableFuture future = CompletableFuture.supplyAsync(() -> {
                try {
                    Upload upload = tm.upload(mediaBucket, objectKey, file);
                    UploadResult result = upload.waitForUploadResult();

                    URL s3Url = s3Client.getUrl(result.getBucketName(), result.getKey());

                    return new UploadInfo(file.getName(), result.getKey(), s3Url.toString());

                } catch (Exception e) {
                    throw new RuntimeException("Failed to upload file: " + file.getName(), e);
                }
            });

            futures.add(future);
        }

        // 等待所有上传完成并聚合结果
        return futures.stream()
                .map(CompletableFuture::join)
                .toList();
    }

    // 使用示例
    public static void main(String[] args) {
        List files = List.of(
            new File("/path/to/photo1.jpg"),
            new File("/path/to/document.pdf"),
            new File("/path/to/avatar.png")
        );

        List results = uploadMultipleFiles(
            "us-east-1",
            "my-media-bucket",
            files,
            "uploads/2025"
        );

        results.forEach(info ->
            System.out.printf("✅ %s → %s%n", info.fileName, info.s3Url)
        );

        // 记得关闭资源（生产环境务必调用）
        // tm.shutdownNow();
        // s3Client.shutdown();
    }
}

? 关键说明与最佳实践：

• ✅ waitForUploadResult() 是核心：它阻塞直至上传完成，并返回含 bucketName 和 key 的 UploadResult，这是构造 URL 的必要输入；
• ? s3Client.getUrl(bucket, key) 返回的是 HTTP 协议的预签名 URL（仅当对象为 public-read 权限时才可直接访问）。若需私有对象的临时访问链接，请改用 generatePresignedUrl()；
• ? Key 命名建议：避免硬编码或重复 Key，推荐加入时间戳、UUID 或业务前缀（如 "user-uploads/{userId}/"），便于权限管理与 CDN 缓存；
• ⚠️ 资源清理：TransferManager 和 AmazonS3 实例应复用（单例模式），并在应用关闭时显式调用 shutdownNow() 释放线程池；
• ? URL 可访问性前提：确保目标 S3 对象已设置为 public-read（通过 Bucket Policy 或对象 ACL），否则即使 URL 正确，浏览器访问也会返回 403。

通过上述方案，你不仅能高效并发上传多个文件，还能精准、可靠地获得每个文件的最终 S3 路径与可分享 URL，为前后端联调、日志记录或数据库持久化提供完整元数据支撑。