amazon/aws-sam-cli-emulation-image-java11 Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

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

一、镜像概述与主要用途

本镜像用于支持 AWS SAM CLI（Serverless Application Model Command Line Interface）的本地测试功能，提供 AWS Lambda 执行环境的本地模拟。通过模拟 Lambda 实际运行环境（包括基础操作系统、运行时依赖及编程模型支持文件），帮助开发人员在本地开发阶段验证 Lambda 函数的行为，无需直接部署至 AWS 云环境，从而提升开发效率并降低测试成本。

二、核心功能与特性

2.1 模拟真实 Lambda 执行环境

• 基于 Amazon Linux 构建，与 AWS 云端 Lambda 运行环境的操作系统基础一致，确保本地测试结果与云端执行行为一致性。

2.2 多语言运行时支持

• 集成 Lambda 官方支持的主流编程语言运行时（如 Python、Node.js、Java、Go、.NET 等），具体版本需根据 SAM CLI 配置或镜像标签指定。

2.3 Lambda 编程模型兼容

• 内置 Lambda 编程模型所需的基础文件与依赖，支持函数处理事件（Event）、上下文对象（Context）、环境变量注入等核心能力，确保本地函数可直接调用 Lambda 标准接口。

2.4 轻量级本地模拟

• 无需依赖实际 AWS 账户资源，通过容器化方式隔离运行环境，支持快速启动与销毁，适合开发阶段高频次迭代测试。

三、使用场景与适用范围

3.1 开发阶段本地测试

• 开发人员在编写 Lambda 函数代码后，可通过本镜像在本地直接运行函数，验证逻辑正确性、输入输出格式及异常处理能力。

3.2 依赖与配置验证

• 测试函数对环境变量、外部依赖（如层 Layer、本地文件）的引用是否正确，避免因依赖缺失或配置错误导致部署后运行失败。

3.3 快速迭代与调试

• 结合 SAM CLI 的热重载能力（如 sam local start-api --hot-reload），修改代码后无需重启容器即可实时查看效果，加速调试流程。

四、使用方法与配置说明

4.1 前提条件

• 已安装 Docker 引擎（推荐版本 20.10+），并确保 Docker 服务正常运行。
• 已安装 AWS SAM CLI（推荐版本 1.0+），用于调用本地测试命令并管理镜像。

4.2 基本使用流程

通过 AWS SAM CLI 命令触发镜像运行，无需手动执行 docker run（SAM CLI 会自动拉取并管理镜像生命周期）。常见命令示例：

4.2.1 本地调用单个 Lambda 函数

bash
sam local invoke "MyLambdaFunction" -e event.json

• 说明：MyLambdaFunction 为 SAM 模板中定义的函数名；-e event.json 指定输入事件文件，镜像将模拟 Lambda 接收该事件并执行函数。

4.2.2 启动本地 API 网关模拟

bash
sam local start-api --port 3000

• 说明：启动本地 HTTP 服务器（端口 3000），将 API 网关请求转发至镜像中的 Lambda 函数，支持通过 http://localhost:3000/endpoint 测试函数。

4.3 配置参数说明

4.3.1 环境变量传递

通过 --env-vars 参数指定环境变量文件，镜像内的 Lambda 函数可读取该变量：

bash
sam local invoke "MyLambdaFunction" --env-vars env.json

env.json 格式示例：

json
{
  "MyLambdaFunction": {
    "DB_CONNECTION_STRING": "local_connection_string",
    "LOG_LEVEL": "debug"
  }
}

4.3.2 本地代码挂载

默认情况下，SAM CLI 会将当前项目目录挂载至镜像内的 /var/task 目录（Lambda 函数代码默认路径），实现代码实时更新。如需自定义挂载路径，可通过 --volume 参数（需配合 docker run 手动启动时使用）：

bash
docker run -v /local/code/path:/var/task amazon/aws-sam-cli-emulation-image

4.3.3 运行时版本指定

通过 SAM 模板（template.yaml）的 Runtime 字段指定函数运行时，镜像将自动匹配对应版本的运行环境：

yaml
Resources:
  MyLambdaFunction:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: python3.9  # 指定 Python 3.9 运行时
      Handler: app.lambda_handler

4.4 部署示例

4.4.1 手动启动容器（docker run 示例）

如需绕过 SAM CLI 直接使用镜像（不推荐，建议通过 SAM CLI 管理）：

bash
docker run -d \
  --name lambda-emulator \
  -p 9000:8080 \
  -v /local/lambda/code:/var/task \
  -e AWS_REGION=us-east-1 \
  amazon/aws-sam-cli-emulation-image:python3.9

• 参数说明：
  • -p 9000:8080：映射容器端口 8080 至本地 9000，用于接收 HTTP 触发请求；
  • -v /local/lambda/code:/var/task：挂载本地代码目录至容器内 Lambda 工作目录；
  • -e AWS_REGION=us-east-1：设置环境变量（模拟 AWS 区域）。

4.4.2 docker-compose 配置示例

yaml
version: '3.8'
services:
  lambda-emulator:
    image: amazon/aws-sam-cli-emulation-image:python3.9
    container_name: lambda-emulator
    ports:
      - "9000:8080"
    volumes:
      - ./lambda-code:/var/task
    environment:
      - AWS_REGION=us-east-1
      - LOG_LEVEL=info
    restart: unless-stopped

• 使用方式：执行 docker-compose up -d 启动容器，通过 curl -X POST http://localhost:9000/2015-03-31/functions/function/invocations -d '{"key":"value"}' 触发函数执行。

五、注意事项

• 镜像版本需与 Lambda 函数运行时版本匹配（如 Python 3.9 对应镜像标签 python3.9），否则可能导致运行时不兼容；
• 本地测试结果仅反映函数逻辑正确性，部分依赖 AWS 服务的功能（如 S3 读写、DynamoDB 访问）需配合 sam local start-lambda 或本地服务模拟工具（如 moto）验证；
• 镜像由 AWS 官方维护，建议通过 SAM CLI 自动拉取最新版本，避免手动指定过时镜像标签。