Node.js应用Docker容器无法连接LocalStack容器如何解决？

报错根因 #

该报错来自AWS SDK的默认逻辑：当SDK未检测到显式配置的AWS凭证时，会自动尝试请求EC2实例元数据服务获取凭证，容器内不存在该服务所以触发报错。本地运行时你的开发环境大概率已有AWS本地凭证配置（比如~/.aws/credentials文件），所以不会触发该问题。

解决步骤 #

1. 补充应用容器的环境变量 #

修改docker-compose.yml中app服务的environment配置，添加LocalStack所需的伪凭证和区域配置（凭证随便填即可，不需要真实AWS凭证）：

environment:
  - S3_ENDPOINT=http://localstack:4566
  - AWS_ACCESS_KEY_ID=test
  - AWS_SECRET_ACCESS_KEY=test
  - AWS_REGION=ap-southeast-1 # 替换为你实际使用的区域即可

2. 修正S3客户端初始化配置 #

初始化AWS S3客户端时，必须显式开启路径寻址模式，否则SDK会默认将桶名拼接到域名前，导致无法正确解析LocalStack地址，以下是JS SDK v3的示例配置：

import { S3Client } from "@aws-sdk/client-s3";

this.s3Client = new S3Client({
  endpoint: process.env.S3_ENDPOINT,
  region: process.env.AWS_REGION,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
  },
  forcePathStyle: true // 该配置为必填项
});

3. 可选网络验证 #

如果修改后仍报错，可先进入应用容器验证网络连通性：
docker compose exec app ping localstack
如果能正常收到返回包，说明Docker网络层面无问题，问题集中在SDK配置项上。

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