AWS Lambda部署自定义Docker镜像报Runtime.InvalidEntrypoint错误

问题现象 #

在AWS Lambda上测试自定义构建的Python业务镜像时触发Runtime.InvalidEntrypoint错误，无公开可检索的对应解决方案。
构建镜像使用的原始Dockerfile如下：

FROM python:3.8

# Copy function code
COPY app.py ${LAMBDA_TASK_ROOT}

#Copy and install requirements
COPY requirements.txt ${LAMBDA_TASK_ROOT}
RUN pip install -r requirements.txt

ARG GITHUB_ACCESS_TOKEN
ARG TABLE_NAME
ARG AWS_ACCESS_KEY
ARG AWS_SECRET_KEY
ARG REGION

ENV GITHUB_ACCESS_TOKEN $GITHUB_ACCESS_TOKEN
ENV TABLE_NAME $TABLE_NAME
ENV AWS_ACCESS_KEY $AWS_ACCESS_KEY
ENV AWS_SECRET_KEY $AWS_SECRET_KEY
ENV REGION $REGION

# Set the CMD to the handler 
CMD [ "app.handler" ]

Lambda输出的完整错误日志如下：

START RequestId: d691e14e-349f-45c5-a4a7-b1b98a3e88be Version: $LATEST
IMAGE   Launch error: exec: "app.handler": executable file not found in $PATH   Entrypoint: []  Cmd: [app.handler]  WorkingDir: []IMAGE Launch error: exec: "app.handler": executable file not found in $PATH   Entrypoint: []  Cmd: [app.handler]  WorkingDir: []END RequestId: d691e14e-349f-45c5-a4a7-b1b98a3e88be
REPORT RequestId: d691e14e-349f-45c5-a4a7-b1b98a3e88be  Duration: 6.80 ms   Billed Duration: 7 ms   Memory Size: 128 MB Max Memory Used: 2 MB   
RequestId: d691e14e-349f-45c5-a4a7-b1b98a3e88be Error: exec: "app.handler": executable file not found in $PATH
Runtime.InvalidEntrypoint

根因分析 #

报错核心原因有两点：

1. 直接使用了Docker Hub官方原生python:3.8作为基础镜像，该镜像未适配Lambda运行时环境，既没有预置Lambda运行时接口客户端（RIC），也没有配置容器启动时的handler加载逻辑，Lambda启动容器时会直接将CMD字段的app.handler作为操作系统级可执行文件去$PATH路径下查找，自然无法找到对应文件。
2. 原生python:3.8镜像中未预定义LAMBDA_TASK_ROOT环境变量，构建时COPY命令引用该空变量，会导致app.py、requirements.txt没有被复制到预期的函数代码目录，进一步加剧启动失败问题。
   额外风险提示：原始Dockerfile将AWS访问密钥、GitHub访问令牌等敏感信息通过ENV指令构建到镜像中，会造成严重的凭证泄露风险，这类敏感配置应当在Lambda函数的环境变量中配置，不要写入镜像构建流程。

解决步骤 #

• 优先选择AWS官方提供的Lambda适配版Python基础镜像替换原生python镜像，Python 3.8对应的适配镜像标识为public.ecr.aws/lambda/python:3.8，该镜像已预配置LAMBDA_TASK_ROOT路径、内置Lambda运行时依赖，无需额外配置启动入口。
• 修正Dockerfile逻辑，移除构建阶段的敏感凭证配置，修正后的参考配置如下：

# 使用Lambda官方适配的Python3.8基础镜像
FROM public.ecr.aws/lambda/python:3.8

# 复制函数代码到预置的任务根目录
COPY app.py ${LAMBDA_TASK_ROOT}

# 复制依赖清单并安装，添加--no-cache-dir减小镜像体积
COPY requirements.txt ${LAMBDA_TASK_ROOT}
RUN pip install -r requirements.txt --no-cache-dir

# 配置函数处理器，官方镜像内置的启动逻辑会自动加载该handler
CMD [ "app.handler" ]

• 若因特殊需求必须使用自定义原生Python基础镜像，需额外补充三项配置：
  1. 安装Lambda运行时接口客户端：在依赖安装阶段执行pip install awslambdaric
  2. 显式定义任务根目录环境变量并切换工作目录：添加ENV LAMBDA_TASK_ROOT=/var/task、WORKDIR ${LAMBDA_TASK_ROOT}配置
  3. 配置正确的入口启动指令：添加ENTRYPOINT [ "/usr/local/bin/python", "-m", "awslambdaric" ]，再保留CMD [ "app.handler" ]作为处理器参数
• 重新构建镜像、推送至ECR仓库，更新Lambda函数关联的镜像版本后即可正常启动。

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