含多入口子目录的AWS Lambda代码仓库中公共代码绝对导入问题的最佳实践咨询

问题背景与复现 #

我有一个名为my_tools的代码仓库，结构如下：

my_tools/
├── commons/
│   ├── __init__.py
│   └── utils.py
├── foo/
│   ├── __init__.py
│   └── fooscript.py
└── __init__.py （空文件）

其中commons/utils.py的代码：

def my_util():
    print("baz")

foo/fooscript.py的代码：

import sys; print(sys.path)
from commons.utils import my_util
my_util()

当我在my_tools根目录运行以下命令时：

python foo/fooscript.py

出现了报错，输出如下：

['/home/michel/my_tools/foo', ... python internals ... ]
Traceback (most recent call last):
File "foo/fooscript.py", line 3, in
from commons.utils import my_util
ModuleNotFoundError: No module named 'commons'

我原本以为在根目录运行Python会把my_tools加入sys.path，但实际上Python只把脚本所在的父目录（也就是foo）加入了路径，即使在根目录添加空的__init__.py也没有效果。

我考虑过的解决方案 #

• 手动将my_tools加入PYTHONPATH环境变量，比如在Makefile的target中配置
• 在代码里修改sys.path：个人认为这个方案比上面的差很多，不希望侵入代码
• 在根目录写一个统一的my_tools.py作为入口包装脚本：这个方案勉强可行，但担心和AWS Lambda的部署需求冲突（Lambda只需要commons目录加单个脚本目录）
• 只用相对导入：因为部署时要把commons放到Lambda层，必须用绝对导入，所以这个方案不可行；虽然可以用自定义Docker镜像，但还是希望能控制工作目录

核心疑问 #

我是不是漏掉了什么更好的方案？如果不想做额外的路径/导入操作，最佳实践真的是修改PYTHONPATH吗？

补充背景：这个问题的复杂性来自于我希望本地调试一个基于AWS Lambda的微服务仓库，其中公共代码要放到Lambda层。

我的解答 #

兄弟，太懂这种本地调试和Lambda部署兼容的痛苦了！结合你的场景，给你几个业界常用的最佳实践方案：

1. 推荐：配置PYTHONPATH（最贴合Lambda部署逻辑）

这个方案其实非常规范，完全符合Python的模块查找机制，而且不会侵入代码。你可以这么做：

• 直接在运行命令前临时设置：

  PYTHONPATH=$(pwd) python foo/fooscript.py
  

• 或者在根目录写个简单的环境脚本setup-env.sh（Linux/macOS）：

  #!/bin/bash
  export PYTHONPATH=$(pwd)
  

  每次运行前先执行source setup-env.sh；如果用Makefile的话，直接把环境变量写在target里：

  run-foo:
      PYTHONPATH=$(pwd) python foo/fooscript.py
  

  这个方案的好处是完美模拟Lambda的环境——Lambda层本质就是把commons放到Python的模块搜索路径里，本地调试时用PYTHONPATH把根目录加进去，代码不需要任何修改，和部署逻辑完全对齐。

2. 用Python的-m参数运行模块（更Pythonic）

这是另一个非常好用的方法，它会自动把当前工作目录加入sys.path。你只需要调整一下脚本结构：

• 把foo/fooscript.py改名为foo/__main__.py，然后在根目录运行：

  python -m foo
  

• 如果不想改文件名，也可以在foo/__init__.py里添加入口逻辑：

  from .fooscript import my_util
  
  if __name__ == "__main__":
      my_util()
  

  同样运行python -m foo就行。这个方案不需要修改环境变量，而且完全兼容Lambda部署——Lambda运行的是单个脚本，你只需要把commons打包成层，foo目录作为Lambda代码上传即可，本地结构和部署结构完全一致。

3. 用包管理工具配置开发环境（适合复杂项目）

如果你的项目用了Poetry、Pipenv或者Pip，可以把本地的my_tools作为可编辑安装的包：

# 用Poetry
poetry add --editable .
# 或者用Pip
pip install -e .

这样Python会自动把根目录加入模块搜索路径，不管你在哪里运行脚本，都能正常导入commons模块。这个方案适合依赖较多的复杂项目，能同时管理依赖和模块路径，部署到Lambda时也只需要把commons打包成层、foo目录作为Lambda代码即可，没有冲突。

总结 #

你考虑的PYTHONPATH方案其实是非常合理的最佳实践之一，另外-m参数运行的方案也很推荐，它更符合Python的模块设计理念。这两个方案都不会侵入代码，完美兼顾本地调试和AWS Lambda的部署需求。

备注：内容来源于stack exchange，提问作者Michel Müller