错误原因分析 #

出现这个报错的核心问题是Python的模块搜索路径（sys.path）不包含你的项目根目录。当你通过main.py执行脚本时，Python默认会把main.py所在的目录加入搜索路径，但如果scripts目录下的脚本在导入时的上下文路径不对，Python就找不到上层的project目录——因为它不在sys.path的搜索列表里。

具体解决方案 #

方案1：手动添加项目根目录到sys.path（推荐，无需修改环境）

在scripts目录下的脚本开头，加入这段代码，动态将项目根目录纳入Python的模块搜索路径：

import sys
from pathlib import Path

# 获取项目根目录（当前脚本的父目录的父目录，即项目最顶层目录）
project_root = Path(__file__).resolve().parent.parent
sys.path.append(str(project_root))

# 现在可以正常导入自定义包了
from project.components.packages.pkg_insert_bdd import Database

这种方法无需修改系统环境变量，能自动适配项目的实际位置，适配不同运行环境。

方案2：设置PYTHONPATH环境变量

将项目根目录添加到PYTHONPATH中，让Python全局搜索该路径下的模块：

• Linux/macOS：在终端执行

  export PYTHONPATH=/absolute/path/to/your/project/root:$PYTHONPATH
  

  若想永久生效，可将该行代码添加到~/.bashrc或~/.zshrc配置文件中。
• Windows：在命令提示符执行

  set PYTHONPATH=C:\absolute\path\to\your\project\root;%PYTHONPATH%
  

  永久生效可通过系统环境变量设置界面添加PYTHONPATH。

方案3：将项目封装为可安装包（适合长期维护的项目）

通过pyproject.toml配置项目，用pip以可编辑模式安装，之后就能像导入标准库一样导入你的自定义包：

1. 在项目根目录创建pyproject.toml文件，内容如下：

   [build-system]
   requires = ["setuptools>=61.0"]
   build-backend = "setuptools.build_meta"
   
   [project]
   name = "your-project-name"
   version = "0.1.0"
   packages = ["project", "scripts"]
   

2. 在终端执行安装命令：

   pip install -e .
   

   安装完成后，无论在哪个目录运行脚本，都能直接导入project包。

项目结构优化建议 #

1. 你当前的目录结构已经满足Python包的基本要求（每个目录都包含__init__.py），这点做得很规范。
2. 如果scripts目录下的脚本都是项目的入口或辅助工具，可以考虑将scripts移至project目录下，变成project/scripts，这样能更自然地使用相对导入（注意：相对导入仅适合在包内部使用，不适合直接运行脚本）。
3. 建议在项目根目录添加README.md（说明项目功能和使用方法）和requirements.txt（记录依赖包版本），方便团队协作和环境配置。

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