VS Code中Python导入文件失败问题求助（附项目结构）

项目文件结构 #

- 10.Testing (根目录)
  -- files/
    |__ __init__.py (空文件)
    |__ simple_functions.py
  -- tests/
    |__ test_simple_functions.py
    |__ __init__.py (空文件)

10.Testing为项目根目录，files存放业务函数代码，tests存放对应的测试文件。

测试代码 #

tests/test_simple_functions.py内容：

# testing the file simple_functions.py

from files.simple_functions import *

def main():
    squared_function(2)

if __name__ == '__main__':
    main()

报错情况 #

运行测试代码时触发导入错误：

Traceback (most recent call last): File "\tests\test_simple_functions.py", line 3, in
from files.simple_functions import *

无论在根目录、tests目录还是files目录下执行（如py tests/test_simple_functions.py或tests> py .\test_simple_functions.py）均失败，但VS Code能识别files.simple_functions模块并支持自动补全。

问题解答 #

1. 项目结构是否符合最佳实践 #

这个结构是标准且合理的，属于源码与测试分离的经典布局，符合Python项目的最佳实践。可以做以下优化让结构更规范：

• 根目录添加pyproject.toml或setup.py，将files声明为可安装包；
• 根目录添加.gitignore（若用Git管理），排除虚拟环境、缓存文件等不必要的内容。

2. 导入报错的原因与解决方法 #

原因

Python模块导入依赖sys.path路径列表，编辑器VS Code会自动把项目根目录加入sys.path，但直接运行测试文件时，sys.path的内容取决于执行目录：

• 在tests目录运行时，sys.path仅包含tests目录，找不到上层的files模块；
• 在根目录运行时，部分场景下Python未将根目录视为合法的包路径，导致导入失败。

解决方法

提供四种可行方案，按推荐程度排序：

方案一：用测试框架运行（推荐）

安装pytest测试框架：

pip install pytest

在项目根目录执行命令运行测试：

pytest tests/test_simple_functions.py -v

pytest会自动识别项目结构，处理模块导入问题，这是Python项目运行测试的标准方式。

方案二：将项目安装为可编辑包（长期维护推荐）

在根目录创建pyproject.toml文件：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "myproject"
version = "0.1.0"
packages = ["files"]

然后在根目录执行：

pip install -e .

安装后files包会被加入Python环境，无论在哪里运行测试代码，都能正常导入。

方案三：手动添加根目录到sys.path

在测试文件开头添加代码，将项目根目录加入sys.path：

import sys
from pathlib import Path

# 获取项目根目录路径
root_dir = Path(__file__).parent.parent
sys.path.append(str(root_dir))

from files.simple_functions import *

def main():
    squared_function(2)

if __name__ == '__main__':
    main()

这种方式无需额外依赖，适合临时调试。

方案四：使用相对导入（需配合模块方式运行）

修改导入语句为相对导入：

from ..files.simple_functions import *

但这种方式需要从根目录以模块方式运行测试文件：

python -m tests.test_simple_functions

不推荐直接运行测试文件时使用，相对导入更适合包内部的模块引用。

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