Python跨目录导入报错：test目录无法识别scripts模块怎么办？

问题原因 #

Python运行脚本时，会将脚本所在的当前目录加入模块搜索路径sys.path。根目录下的main.py运行时，根目录在搜索路径中，因此能识别scripts子模块；但test/test_scripts.py运行时，当前目录是test，项目根目录不在搜索路径中，所以找不到scripts模块。

以下是几种实用解决方法：

• 方法1：在测试脚本中手动添加项目根目录到搜索路径
  在test_scripts.py开头添加代码，将项目根目录（test文件夹的父目录）加入sys.path：

  import sys
  from pathlib import Path
  
  # 获取项目根目录（当前脚本所在目录的父目录）
  root_dir = Path(__file__).resolve().parent.parent
  sys.path.append(str(root_dir))
  
  # 后续正常导入模块
  from scripts.helpful_scripts import *
  from scripts.print_something import *
  
  print(add(1, 2))
  print_something()
  

  优点：无需额外配置，修改单个脚本即可生效；缺点：每个测试脚本都需添加这段代码。

• 方法2：从项目根目录以模块方式运行测试脚本
  切换到项目根目录，执行以下命令运行测试脚本：

  python -m test.test_scripts
  

  这种方式会自动将项目根目录加入模块搜索路径，无需修改代码。
  优点：不用改代码，适合日常测试；缺点：每次需从根目录执行命令。

• 方法3：设置PYTHONPATH环境变量
  将项目根目录添加到PYTHONPATH，让Python全局识别该路径下的模块：

  • Linux/macOS终端：

    export PYTHONPATH=/path/to/your/project/root
    

  • Windows命令提示符：

    set PYTHONPATH=C:\path\to\your\project\root
    

  设置后，任何目录下运行test_scripts.py都能正常导入模块。
  优点：一次配置，所有脚本生效；缺点：仅当前终端会话有效，可写入shell配置文件实现永久生效。

• 方法4：将项目安装为可编辑模块
  在项目根目录创建setup.py文件：

  from setuptools import setup, find_packages
  
  setup(
      name="your-project",
      version="0.1.0",
      packages=find_packages(),
  )
  

  然后在根目录执行命令安装可编辑版本：

  pip install -e .
  

  这样scripts会被注册为全局模块，任何位置的脚本都能直接导入。
  优点：适合长期开发项目，无需额外路径配置；缺点：需创建配置文件，更适合正式项目。

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