Testcontainers+LocalStack S3虚拟主机寻址配置失效求助

1. 网络别名配置要带完整域名后缀 #

虚拟主机寻址依赖{bucketName}.localhost.localstack.cloud格式的域名解析，你只加存储桶名作为网络别名是不够的。正确的配置应该是：

localStackContainer.withNetworkAliases("testBucket.localhost.localstack.cloud");

同时必须用自定义Docker网络（不要用默认桥接），否则容器间的DNS解析无法生效。

2. 开启LocalStack的S3虚拟主机支持 #

LocalStack默认可能没启用这个功能，启动容器时要加环境变量：

localStackContainer.withEnv("S3_VIRTUAL_HOST", "true");

另外确保LocalStack版本在0.14.0以上，旧版本对虚拟主机寻址的支持有缺陷。

3. AWS SDK V2的关键配置不能错 #

SDK V2的几个核心设置直接影响寻址模式：

• 必须禁用路径风格访问：
• 端点只指向LocalStack根地址，不能带存储桶名
• 区域要和LocalStack默认的us-east-1一致

示例客户端代码：

S3Client s3Client = S3Client.builder()
    .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create("test", "test")))
    .endpointOverride(URI.create("http://localhost.localstack.cloud:4566"))
    .region(Region.US_EAST_1)
    .serviceConfiguration(S3Configuration.builder()
        .pathStyleAccessEnabled(false)
        .build())
    .build();

4. 存储桶创建的时机和方式要对 #

• 必须在SDK客户端初始化前创建桶，用LocalStack的awslocal命令创建最稳妥：

localStackContainer.execInContainer("awslocal", "s3", "mb", "s3://testBucket");

别手动构造带域名的桶名，直接用纯桶名即可，LocalStack会自动关联虚拟主机配置。

• 可以检查命令执行的退出码，确保桶创建成功：

ExecResult result = localStackContainer.execInContainer("awslocal", "s3", "mb", "s3://testBucket");
if (result.getExitCode() != 0) {
    throw new RuntimeException("Failed to create bucket: " + result.getStderr());
}

5. 应用容器的环境配置检查 #

如果是在另一个应用容器里访问，要确认：

• 应用容器和LocalStack在同一个自定义Docker网络中
• 应用容器的DNS配置正常，没有自定义DNS导致无法解析testBucket.localhost.localstack.cloud
• 应用内的SDK配置和上述要求完全一致，尤其是路径风格禁用和端点设置

6. 快速调试技巧 #

• 在应用容器内用curl测试：curl http://testBucket.localhost.localstack.cloud:4566，如果返回XML格式的桶信息，说明LocalStack侧没问题，问题出在SDK；如果还是404，检查DNS解析或LocalStack配置。
• 开启SDK DEBUG日志，查看实际请求URL：添加logging.level software.amazon.awssdk=DEBUG，确认请求是虚拟主机格式而非路径格式。

内容的提问来源于stack exchange，提问作者David S