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 函数

sam local invoke "MyLambdaFunction" -e event.json

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

4.2.2 启动本地 API 网关模拟

sam local start-api --port 3000

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

4.3 配置参数说明

4.3.1 环境变量传递

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

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

env.json 格式示例：

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

4.3.2 本地代码挂载

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

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

4.3.3 运行时版本指定

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

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 管理）：

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 配置示例

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 自动拉取最新版本，避免手动指定过时镜像标签。