如何配置Python开发环境让CLI优先加载本地文件夹的模块？

报错核心原因 #

报错的核心原因分为两层：

• 目录结构不符合Python包规范，本地文件路径冲突：当前将所有源码文件散放在项目根目录，且lightweight_gan是单文件模块而非包含子模块的文件夹包。执行from lightweight_gan.diff_augment import xxx这类导入时，Python会优先在当前目录的靠前搜索路径里找到这个单文件，由于普通py文件无法作为包层级导入子模块，因此抛出'lightweight_gan' is not a package的报错。
• Python模块搜索路径优先级机制：Python运行时加载模块的搜索顺序为「当前脚本所在目录 → PYTHONPATH指定路径 → 虚拟环境site-packages目录 → 系统全局Python路径」。如果曾在虚拟环境中安装过正式版的同名包，只要当前目录的结构无法让Python识别为合法的源码包路径，就会自动加载site-packages里的旧版本代码，跳过本地修改的文件。

标准开发环境搭建步骤 #

第一步：调整为规范的Python包目录结构 #

将所有源码文件移入与包名同名的独立文件夹，保证导入层级可被Python正确识别，调整后的结构如下：

项目根目录/
├── pyproject.toml  # 包配置文件（用于可编辑安装）
└── lightweight_gan/
    ├── __init__.py
    ├── cli.py
    ├── diff_augment.py
    ├── diff_augment_test.py
    ├── lightweight_gan.py
    └── version.py

第二步：选择适配的模块加载方案，保证本地代码优先被加载 #

• 方案一：可编辑本地安装（官方推荐长期开发使用）
  在项目根目录配置好pyproject.toml的CLI入口映射后，激活开发虚拟环境，执行安装命令：
  pip install -e .
  该操作会将本地的源码路径以软链接的形式关联到虚拟环境的site-packages目录，后续修改本地代码无需重复安装，CLI运行时会直接加载本地最新的代码文件，避免加载虚拟环境旧包的问题。
• 方案二：临时调试路径注入（适合快速局部验证）
  如果暂时不需要做正式的包配置，可在运行CLI时通过PYTHONPATH环境变量将当前目录注入到模块搜索路径的最高优先级，执行命令示例：
  PYTHONPATH=. python lightweight_gan/cli.py
  该方法会让Python优先从当前工作目录查找模块，跳过虚拟环境中旧版本的包文件。注意使用该方案时必须保证导入语句和目录层级匹配，否则仍会抛出模块不存在的错误。
• 方案三：清理虚拟环境旧版本包
  如果之前通过pip在虚拟环境中安装过同名的正式版包，可执行卸载命令移除旧版本：
  pip uninstall lightweight-gan
  移除后虚拟环境中不再存在该包的正式安装版本，Python会自动回溯查找本地目录下的源码文件完成加载。

避坑提醒 #

• 不要在项目根目录下放和包名同名的单文件，必须将所有包源码放入与包名同名的独立文件夹，通过「同名文件夹 + init.py」的结构定义Python包，否则会频繁出现“非包模块”的识别错误。
• 长期开发场景不要用普通模式反复pip install .安装，这种模式会将源码复制到site-packages目录，每次修改本地代码都要重新安装才能生效，开发效率极低。

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