AWS SAM CLI Lambda 本地执行环境镜像

镜像概述和主要用途

该镜像为 AWS SAM CLI（Serverless Application Model Command Line Interface）提供本地测试支持，用于模拟 AWS Lambda 的执行环境。它基于 Amazon Linux 构建，集成了 Lambda 运行时所需的编程语言软件及核心文件，支持开发者在本地环境验证 Lambda 函数逻辑，无需直接部署至 AWS 云环境。

核心功能和特性

• 模拟 Lambda 生产环境：复刻 AWS Lambda 云端执行环境，包括 Amazon Linux 基础系统、系统库及安全策略，确保本地测试与云端运行一致性。
• 多运行时支持：集成 Lambda 官方支持的主流编程语言运行时（如 Python、Node.js、Java、Go、.NET 等），匹配云端 runtime 版本。
• Lambda 编程模型兼容：包含运行时接口客户端（Runtime Interface Client）、日志处理机制及环境变量注入逻辑，支持 Lambda 函数入口规范（如 handler 函数）。
• 轻量级触发模拟：支持通过 SAM CLI 模拟 API Gateway、S3、SQS 等 Lambda 触发器，验证函数对事件的响应逻辑。

使用场景和适用范围

• 本地开发与调试：开发者可在本地编写 Lambda 函数后，快速验证代码逻辑、依赖项及配置正确性，减少云端部署次数。
• 跨环境一致性保障：确保开发、测试、CI/CD 流程使用统一的运行时环境，规避因环境差异导致的"本地正常、云端异常"问题。
• 离线功能验证：在无网络连接或 AWS 服务访问受限场景下，仍可完成 Lambda 函数基础功能测试。
• CI/CD 流程集成：作为自动化测试环节的一部分，在代码提交或构建阶段执行单元测试，提前发现运行时错误。

使用方法和配置说明

前提条件

• 安装 AWS SAM CLI（建议版本 1.0.0+）
• 安装 Docker 引擎（用于镜像拉取和容器管理）

典型使用流程（通过 SAM CLI 调用）

该镜像通常由 SAM CLI 自动管理，无需手动执行 docker run。通过以下 SAM CLI 命令触发本地测试时，镜像会被自动拉取并启动：

# 本地调用指定 Lambda 函数（需提前准备事件文件 event.json）
sam local invoke "FunctionName" -e event.json

# 启动本地 API Gateway 模拟服务（用于测试 HTTP 触发型函数）
sam local start-api

# 启动 Lambda 本地模拟器（支持通过 AWS SDK 或 CLI 触发函数）
sam local start-lambda

手动运行镜像（高级场景）

如需自定义测试环境（如修改运行时参数、挂载本地依赖），可手动启动容器：

docker run -d \
  --name lambda-local-env \
  -v /本地函数代码目录:/var/task \  # 挂载 Lambda 函数代码（必填）
  -e AWS_REGION="us-east-1" \       # 设置 AWS 区域（影响 SDK 客户端默认配置）
  -e LAMBDA_TASK_ROOT="/var/task" \ # 指定函数代码根目录（固定为 /var/task）
  -e LAMBDA_FUNCTION_NAME="MyFunc" \# 函数名称（自定义）
  -p 9000:8080 \                    # 映射运行时接口端口（8080 为 RIE 默认端口）
  amazon/aws-sam-cli-emulation-image-<runtime>:<tag>  # 替换为具体 runtime 和标签

说明：

• <runtime> 需替换为目标函数运行时（如 python3.9、nodejs18.x）；
• <tag> 为镜像版本标签（如 latest 或具体版本号，可从 AWS ECR 仓库 获取）。

Docker Compose 配置示例

在多服务依赖场景（如 Lambda + 本地 DynamoDB）中，可通过 Docker Compose 集成：

version: '3.8'
services:
  lambda:
    image: amazon/aws-sam-cli-emulation-image-python3.9:latest
    volumes:
      - ./lambda-code:/var/task  # 挂载本地函数代码
    environment:
      - AWS_REGION=us-west-2
      - DYNAMODB_ENDPOINT=[***]  # 指向本地 DynamoDB 服务
    ports:
      - "9000:8080"  # 暴露 RIE 接口，用于接收函数调用请求
    depends_on:
      - dynamodb

  dynamodb:
    image: amazon/dynamodb-local:latest
    ports:
      - "8000:8000"
    command: "-jar DynamoDBLocal.jar -inMemory"  # 内存模式运行（数据不持久化）

核心配置参数与环境变量

必配环境变量

可选环境变量

目录挂载要求

• /var/task：必须挂载本地 Lambda 函数代码目录，包含函数入口文件（如 handler.py、index.js）及依赖文件（如 requirements.txt、node_modules）。
• /tmp：Lambda 函数临时存储目录，如需持久化临时文件可挂载本地目录（如 -v /本地临时目录:/tmp）。
• /var/runtime：运行时依赖目录（镜像内置，通常无需挂载，除非需自定义 runtime 文件）。

注意事项

1. 运行时版本匹配：需根据函数运行时选择对应镜像（如 Python 3.9 函数需使用 amazon/aws-sam-cli-emulation-image-python3.9），版本不匹配会导致运行时错误。
2. 网络互通性：若函数需访问本地其他服务（如 DynamoDB Local），需确保容器网络互通（推荐使用 Docker Compose 统一网络或自定义桥接网络）。
3. 文件权限：挂载本地目录时，确保容器内用户（默认 sbx_user1051）对挂载目录有读权限，避免因权限不足导致函数加载失败（可通过 chmod 755 /本地目录 调整）。
4. 镜像拉取源：镜像托管于 AWS ECR Public Gallery，需确保网络可访问 public.ecr.aws 仓库（国内用户可配置镜像加速）。