Mac M1本地运行Lambda函数时SAM CLI构建Docker镜像失败

环境信息 #

• 主机：Mac M1
• SAM版本：1.70.0
• CDK版本：2.60.0（构建版本2d40d77）
• 架构配置：通过CDK创建API Gateway REST端点 + 触发式Lambda函数，cdk synth/cdk deploy可正常执行，但sam local invoke/sam local start-api报错

错误信息 #

% sam local invoke GetUserTemporary -t cdk.out/api.template.json -e events/get_user/prod-user.json

Invoking get_user_temporary.handler.handle (python3.9)
DependenciesLayerDF300E31 is a local Layer in the template
Local image was not found.
Building image.......................................................................................................................................................................................................................................................................................................................
Failed to build Docker Image
NoneType: None
Error: Error building docker image: The command '/bin/sh -c mv /var/rapid/aws-lambda-rie-x86_64 /var/rapid/aws-lambda-rie && chmod +x /var/rapid/aws-lambda-rie' returned a non-zero code: 1

解决方案 #

1. 清理SAM本地缓存 #

清除SAM本地存储的旧镜像和层缓存，避免x86架构镜像残留干扰：

sam local delete-all

也可手动清理Docker中的SAM相关镜像：

docker rmi $(docker images -q "public.ecr.aws/sam/*")

2. 强制指定ARM64架构执行SAM命令 #

M1为arm64架构，执行本地命令时显式指定平台：

sam local invoke GetUserTemporary -t cdk.out/api.template.json -e events/get_user/prod-user.json --platform linux/arm64

启动本地API服务时同理：

sam local start-api -t cdk.out/api.template.json --platform linux/arm64

3. 调整Docker Desktop架构配置 #

打开Docker Desktop，检查并修改以下设置：

• 进入Settings -> Features in development，确保Use the new Virtualization framework已开启
• 进入Settings -> Resources -> Advanced，确认架构设置为arm64
• 重启Docker Desktop使配置生效

4. 升级SAM和Docker版本 #

旧版本可能存在M1架构兼容问题：

• 升级SAM CLI（brew安装场景）：

  brew upgrade aws-sam-cli
  

• 升级Docker Desktop至最新稳定版

5. 显式指定CDK层的ARM64架构 #

在api_stack.py中定义Lambda层时，明确指定兼容架构，避免生成x86配置：

from aws_cdk import aws_lambda as lambda_

deps_layer = lambda_.LayerVersion(
    self, "DependenciesLayer",
    code=lambda_.Code.from_asset("path/to/layer"),
    compatible_runtimes=[lambda_.Runtime.PYTHON_3_9],
    compatible_architectures=[lambda_.Architecture.ARM_64]
)

修改后重新执行cdk synth生成新模板，再进行本地测试。

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