VS Code中Python模块导入报错求助（NameError）

问题背景 #

运行多人协作Python项目时触发错误：

File "D:\projects\company\spiders\country\spain\cities\runnables\short.py", line 22, in <module>
    soup = get_soup_from_url(url, "html.parser")
NameError: name 'get_soup_from_url' is not defined

仅本地环境出现该问题，团队成员使用相同VS Code + Windows 10配置可正常运行。已通过测试项目复现错误，项目结构及代码如下：

测试项目结构 #

- spiders
   - country
      - spain
         - cities
            - runnable
               - short.py
   - utils
      - driver.py

测试代码 #

short.py

import sys

sys.path.append('../../../../utils')

from driver import *

print_on_console('Hello world!')

driver.py

def print_on_console(message):
    print(message)

解决方案 #

1. 替换相对路径为绝对路径 #

sys.path.append的相对路径依赖终端当前工作目录，而非脚本所在目录，容易导致路径错误。修改short.py，基于脚本位置生成绝对路径：

import sys
import os

# 获取脚本所在绝对目录
script_dir = os.path.dirname(os.path.abspath(__file__))
# 拼接utils目录的绝对路径
utils_abs_path = os.path.join(script_dir, '../../../../utils')
sys.path.append(utils_abs_path)

from driver import print_on_console

print_on_console('Hello world!')

2. 确认VS Code工作目录 #

确保VS Code打开的是项目根目录（即包含spiders文件夹的上级目录）：

• 通过文件 > 打开文件夹选择项目根目录
• 检查终端当前路径，确保为项目根目录，而非short.py所在的runnable子目录

3. 对齐Python解释器环境 #

验证本地Python解释器与团队成员一致：

• 点击VS Code左下角的Python版本标识，切换至团队使用的解释器（含虚拟环境）
• 终端执行python --version，对比版本号

4. 将utils转为Python包（长期解决方案） #

在utils目录下创建空的__init__.py文件，将其标记为Python包：

- spiders
   - ...
   - utils
      - __init__.py
      - driver.py

在项目根目录创建.env文件，添加Python路径配置：

PYTHONPATH=.

之后short.py可直接使用绝对导入：

from spiders.utils.driver import print_on_console

print_on_console('Hello world!')

5. 配置调试工作目录（若使用调试模式） #

若通过VS Code调试运行代码，在launch.json中指定工作目录为项目根：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "cwd": "${workspaceFolder}"
        }
    ]
}

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