TypeScript编写的Lambda无法连接LocalStack DynamoDB：连接被拒

问题场景 #

使用LocalStack模拟AWS资源时，TypeScript编写的Lambda函数连接LocalStack中的DynamoDB，触发ECONNREFUSED连接拒绝错误，但通过AWS CLI可以正常扫描表获取数据。

错误详情 #

{
    "errno": -111,
    "code": "ECONNREFUSED",
    "syscall": "connect",
    "address": "127.0.0.1",
    "port": 4566,
    "$metadata": {
        "attempts": 3,
        "totalRetryDelay": 32
    }
}

现有Lambda代码 #

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
  DynamoDBDocumentClient,
  ScanCommand
} from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({
    region: process.env.CDK_DEFAULT_REGION,
    endpoint: 'http://localhost:4566',
});

const dynamo = DynamoDBDocumentClient.from(client);
const TABLE_NAME = process.env.TABLE_NAME || '';

export const handler = async (event: any) => {
    try {
        console.log('connecting to dyname db: ' +  TABLE_NAME)
        var body = await dynamo.send(
            new ScanCommand({ TableName: TABLE_NAME })
          );          
        const response = body?.Items;
        return { statusCode: 200, body: JSON.stringify(response) };
    } catch (dbError) {  
        console.log('Unable to get the data from dyname db: ' +  TABLE_NAME)      
        return { statusCode: 500, body: JSON.stringify(dbError) };
    }
};

可正常执行的CLI命令 #

aws --endpoint-url=http://localhost:4566 dynamodb scan --table-name <table-name>

核心原因及解决方法 #

1. Lambda容器无法访问宿主机的LocalStack #

Lambda在LocalStack容器内运行时，localhost指向的是Lambda容器自身，而非运行LocalStack的宿主机，这是最常见的触发原因。

解决方式：

• 根据操作系统替换endpoint中的地址：
  • Windows/macOS环境，使用host.docker.internal映射宿主机：

    const client = new DynamoDBClient({
        region: process.env.CDK_DEFAULT_REGION,
        endpoint: 'http://host.docker.internal:4566',
    });
    

  • Linux环境，使用宿主机Docker网桥默认IP172.17.0.1：

    const client = new DynamoDBClient({
        region: process.env.CDK_DEFAULT_REGION,
        endpoint: 'http://172.17.0.1:4566',
    });
    

  • 若用Docker Compose部署，直接使用LocalStack服务名称（如localstack）：

    const client = new DynamoDBClient({
        region: process.env.CDK_DEFAULT_REGION,
        endpoint: 'http://localstack:4566',
    });
    

2. 环境变量未正确传递 #

Lambda可能未获取到CDK_DEFAULT_REGION或TABLE_NAME的有效值，导致配置异常。

解决方式：

• 部署Lambda时确认环境变量已正确配置，可在代码中添加日志验证：

  console.log('当前区域:', process.env.CDK_DEFAULT_REGION);
  console.log('目标表名:', TABLE_NAME);
  

3. LocalStack端口映射异常 #

虽然CLI能访问，但Lambda所在网络可能无法触及4566端口。

解决方式：

• 检查LocalStack启动命令是否包含端口映射参数-p 4566:4566；
• 验证宿主机防火墙是否允许4566端口的入站连接。

4. AWS SDK缺少基础配置 #

部分SDK版本需要凭证配置（LocalStack接受任意格式的有效凭证）。

解决方式：

• 在DynamoDBClient初始化时添加凭证配置：

  const client = new DynamoDBClient({
      region: process.env.CDK_DEFAULT_REGION,
      endpoint: 'http://host.docker.internal:4566',
      credentials: {
          accessKeyId: 'test',
          secretAccessKey: 'test'
      }
  });
  

验证步骤 #

修改代码后重新部署Lambda，执行测试：

1. 查看Lambda日志确认连接地址是否正确；
2. 触发Lambda，检查是否能正常返回DynamoDB数据。

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