从Lambda Layer导入代码到Lambda函数持续报导入错误

API 探路者

2026-8-29

问题根因

这个报错和Lambda Layer的包结构、自定义模块内部的导入逻辑直接相关，pip依赖可以正常使用说明Layer的基础路径配置没有大问题，核心错误点有两个：

自定义model包内部存在错误的跨层级相对导入
Python触发attempted relative import beyond top-level package错误的直接原因，是代码中使用了超出当前顶级包范围的相对导入。当Lambda加载Layer中的model包时，会将model识别为顶级包（因为它的父目录在Python的sys.path搜索列表中，没有上层包结构），如果model目录下的__init__.py、a.py、b.py中存在from .. import xxx这类向上跨层级的相对导入语句，就会直接触发该错误——顶级包不存在父级包，无法完成相对引用。
Layer打包混入冗余工程文件，存在包识别干扰风险
你当前Layer工程根目录下的__init__.py、LICENSE、README.md、samconfig.toml、template.yaml等文件都属于本地开发/SAM配置文件，如果直接在工程根目录打包，这些文件会被直接放到Layer解压后的/opt目录下，冗余的__init__.py可能干扰Python对包结构的判断。
（低概率诱因）Lambda函数的CodeUri配置不规范
如果SAM模板中Lambda的CodeUri指向项目根目录、Handler配置为src.app.xxx，会导致src被识别为顶级包，若此时src下的模块混用相对/绝对导入，也可能触发同类导入错误。

修复方案

按以下步骤调整即可解决问题：

调整Layer目录结构，规范打包逻辑
打包Lambda Layer时，zip包内只保留必要的运行时文件，移除所有本地开发配置文件，同时将自定义model包放到和pip依赖相同的site-packages路径下（该路径100%会被Lambda运行时加入sys.path，避免路径识别偏差），最终打包的Layer zip内部结构严格保持如下：
```
└── python
    └── lib
        └── python3.9
            └── site-packages
                ├── （所有pip安装的第三方依赖包目录）
                └── model
                    ├── __init__.py
                    ├── a.py
                    └── b.py
```
打包时在python目录的同级位置执行zip命令，确保解压后python目录直接位于/opt路径下，不要额外嵌套工程名文件夹。
修正model包内部的导入语句
检查model包下所有.py文件的导入逻辑：
- 删除所有from .. import xxx这类超出model包层级的相对导入，统一改为绝对导入写法
- model包内部的同级模块导入可以保留相对导入（比如a.py导入b.py写from . import b），这类导入不会超出model包层级，不会触发错误
规范Lambda函数的工程配置
调整SAM模板中Lambda函数的配置：
- CodeUri指向src目录，确保打包后的Lambda代码zip根目录直接是app.py、db.py等业务文件，不嵌套src文件夹
- Handler配置为app.<你的handler函数名>，比如函数入口是app.py里的lambda_handler，就写app.lambda_handler
- 业务代码中统一使用绝对导入：比如app.py导入db.py写import db，db.py导入model下的a模块直接写from model import a即可，不要用相对导入引用同级业务模块
验证方法
重新构建发布Layer版本并绑定到Lambda后，可以先在app.py开头加两行测试代码确认路径：
```
import sys
print(sys.path)
```
执行后确认输出的路径列表中包含/opt/python/lib/python3.9/site-packages，再测试导入逻辑即可。

避坑提示：如果调整后出现ModuleNotFoundError: No module named 'model'，99%是Layer打包的目录层级错了，检查zip包内部是不是多套了一层文件夹，确保python目录在zip根目录。

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