MacOS下Spring Boot集成测试遇UnknownHostException: localhost.localstack.cloud

运行Spring Boot应用的集成测试时，使用Localstack模拟Amazon S3服务，遇到如下异常：

Caused by: software.amazon.awssdk.core.exception.SdkClientException: Unable to execute HTTP request: localhost.localstack.cloud
at app//software.amazon.awssdk.core.exception.SdkClientException$BuilderImpl.build(SdkClientException.java:111)
at app//software.amazon.awssdk.core.exception.SdkClientException.create(SdkClientException.java:47)
at app//software.amazon.awssdk.core.internal.http.pipeline.stages.utils.RetryableStageHelper.setLastException(RetryableStageHelper.java:223)

常见排查与解决步骤 #

• 检查Localstack服务状态：确认Localstack容器正常启动，S3服务已启用（可执行localstack status services命令查看）
• 修正端点配置：确保S3客户端配置的endpoint为Localstack实际地址（通常是http://localhost:4566），而非AWS官方地址
• 处理DNS解析问题：若localhost.localstack.cloud无法解析，在本地hosts文件添加映射：127.0.0.1 localhost.localstack.cloud
• 校验版本兼容性：检查Localstack版本与AWS SDK版本是否匹配，避免版本差异引发通信问题
• 调整客户端SSL配置：Localstack默认使用HTTP，需在S3客户端配置中关闭SSL验证

内容的提问来源于stack exchange，提问作者Zekarias Taye Hirpo