如何配置Java应用使用LocalStack？解决UnknownHostException异常

问题根源 #

报错UnknownHostException: my-bucket.localhost的核心原因是：AWS SDK Java 2.x的S3客户端默认采用虚拟主机样式请求（将存储桶名拼接在域名前，如my-bucket.localhost），但LocalStack默认需要路径样式请求（存储桶名放在URL路径中，如http://localhost:4566/my-bucket）。同时，.aws/config中的全局endpoint_url配置对S3客户端优先级较低，SDK不会自动套用该地址生成正确请求路径。

而AWS CLI能正常工作，是因为CLI针对LocalStack场景自动适配了路径样式访问逻辑。

解决方案 #

方案1：代码显式配置S3客户端（推荐，最可靠） #

直接在构建S3Client时指定LocalStack端点，并强制启用路径样式访问：

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.S3Configuration;
import java.net.URI;

public class S3LocalStackClient {
    public static void main(String[] args) {
        // 启用S3路径样式访问
        S3Configuration s3Config = S3Configuration.builder()
                .pathStyleAccessEnabled(true)
                .build();

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

        // 执行存储桶操作示例
        s3Client.listObjects(req -> req.bucket("my-bucket"));
    }
}

方案2：修改AWS配置文件（无需修改代码） #

在.aws/config的localstack配置段中，添加S3专属配置项：

[profile localstack]
region = us-east-1
output = json
endpoint_url = http://localhost:4566
# S3专属配置：指定端点+开启路径样式
s3 =
    endpoint_url = http://localhost:4566
    path_style = true

保持JVM启动参数-Daws.profile=localstack不变，SDK会自动读取配置生成正确的S3客户端。

方案3：JVM系统属性快速配置（调试场景） #

直接在启动参数中添加两个系统属性，强制S3使用路径样式并指定端点：

-Daws.profile=localstack \
-Daws.s3.path-style-access=true \
-Daws.service.endpoint-override.s3=http://localhost:4566

验证 #

配置完成后重新运行Java应用，即可正常连接LocalStack的S3服务，不再出现UnknownHostException。

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