使用Java向AWS S3存储桶文件夹上传文件时路径编码问题求助

错误原因分析 #

1. 斜杠被编码为%2f：LocalStack默认用文件系统模拟S3存储，会对对象键中的特殊字符（包括/）做URL编码，导致本地生成的路径里出现%2f而非正常的目录分隔符，系统无法识别该路径。
2. 路径末尾出现@null：这是LocalStack处理对象版本ID的逻辑问题，当未指定对象版本ID时，错误地在路径末尾追加@null，导致路径无效。

解决方法 #

1. 禁用LocalStack的键编码功能 #

在Docker Compose的LocalStack服务配置里添加环境变量S3_DISABLE_KEY_ENCODING=1，关闭对对象键的URL编码，保留/作为目录分隔符的原始逻辑。

示例Docker Compose配置片段：

services:
  localstack:
    image: localstack/localstack:latest
    environment:
      - SERVICES=s3
      - S3_DISABLE_KEY_ENCODING=1
      - DEFAULT_REGION=us-east-1
    ports:
      - "4566:4566"
    volumes:
      - "./persisted-data:/var/lib/localstack"

2. 修正Java SDK的LocalStack连接配置 #

Java AWS SDK默认连接官方S3服务，需手动指定LocalStack的端点地址和测试凭证，避免请求处理异常：

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import java.net.URI;

// ... 其他代码保持不变

S3Client s3 = S3Client.builder()
        .region(Region.US_EAST_1)
        .endpointOverride(URI.create("http://localhost:4566")) // 指向LocalStack端点
        .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create("test", "test"))) // 测试用凭证
        .build();

注意：LocalStack不需要真实AWS凭证，填写任意非空值即可。

3. 检查持久化卷配置 #

确保Docker Compose中挂载的持久化卷路径存在且权限充足，避免因目录不存在或权限问题导致路径解析错误。

补充说明 #

S3本身是对象存储，没有物理文件夹概念，/仅作为对象键的逻辑分隔符。LocalStack用文件系统模拟时，默认的键编码行为会破坏这种逻辑，禁用编码后即可和官方S3行为保持一致。此外，更新LocalStack到最新版本也可能修复@null这类版本处理的bug。

内容的提问来源于stack exchange，提问作者Tyali Nexi