AWS Lambda Docker部署自定义Python库报Runtime.ImportModuleError问题

你的部署方式存在几个容易踩的配置坑，核心是本地模拟器和真实Lambda运行环境的Python模块搜索规则不一致，才会出现本地通、线上报错的情况。

现有配置的问题点 #

• 你写的CMD mkdir -p /workspace完全无效：CMD是容器启动阶段才会执行的命令，镜像构建过程中不会运行，这行写了等于没写，不过这不是导致报错的核心原因。
• 核心问题出在pip安装步骤：你在/workspace目录下执行pip3 install . --target "${LAMBDA_TASK_ROOT}"时，如果自定义库的包发现配置有问题、或者复制到构建上下文的库文件不全，pip会静默安装一个只有.dist-info元数据的空包到/var/task（也就是LAMBDA_TASK_ROOT）。本地用Runtime Interface Emulator测试时，启动逻辑会自动把构建时的工作目录/workspace加到Python搜索路径里，所以Python能找到/workspace下的源码正常运行；但真实Lambda环境的Python默认只搜索/var/task和系统site-packages目录，不会扫描/workspace，自然就会报找不到自定义库的错误。
• 额外排查点：Linux环境文件名大小写敏感，如果你本地开发是在macOS/Windows上，import的模块名和实际文件夹名大小写不一致，本地不会报错，上线就会触发导入错误。

验证方法 #

本地构建完镜像后，直接执行命令查看/var/task下的文件，不需要启动模拟器：

docker run --rm --entrypoint ls 你的镜像标签 /var/task | grep 你的自定义库名

如果只能找到类似MY_LIBRARY-0.0.1.dist-info的目录，找不到和库名一致的源码文件夹，就可以确认是上述安装步骤的问题。

修复方案 #

二选一即可：

• 修正构建流程，确保库文件正确安装到任务目录

  FROM public.ecr.aws/lambda/python:3.9
  
  # 删掉无效的mkdir命令，WORKDIR会自动创建不存在的目录
  WORKDIR /build
  # 先复制安装所需的配置文件和库源码，顺序调整后还能利用Docker构建缓存
  COPY setup.py pyproject.toml README.md ./
  COPY MY_LIBRARY ./MY_LIBRARY/
  # 安装后加一步检查，构建阶段就能发现文件没装对的问题，不用等上线才踩坑
  RUN pip3 install . --target "${LAMBDA_TASK_ROOT}" && \
      ls -la "${LAMBDA_TASK_ROOT}"/MY_LIBRARY
  # 最后复制Lambda处理脚本
  COPY preprocessing.py "${LAMBDA_TASK_ROOT}/"
  

• 直接全局安装自定义库，省去路径配置的麻烦
  不需要用--target参数，直接把库装到Python默认的site-packages目录，不管工作目录怎么变Python都能搜到模块：

  FROM public.ecr.aws/lambda/python:3.9
  WORKDIR /build
  COPY setup.py pyproject.toml ./
  COPY MY_LIBRARY ./MY_LIBRARY/
  RUN pip3 install .
  COPY preprocessing.py "${LAMBDA_TASK_ROOT}/"
  

注意：不要完全依赖本地Runtime Interface Emulator的测试结果判断模块路径配置是否正确，它的路径加载逻辑和真实Lambda环境存在差异，涉及模块导入的场景最好进容器直接检查对应目录下的文件是否存在。

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