Python中utils.py模块的正确创建方法及导入运行报错解决

这个问题我之前也碰到过，核心原因是编辑器的代码分析路径和Python运行时的模块搜索路径不是一回事儿：VS Code的python.analysis.extraPaths只是给代码提示、语法检查这些语言服务用的，Python实际跑代码的时候根本不会读取这个配置，所以就出现了编辑器不报错但运行时找不到模块的尴尬情况。

下面是几种正确的解决方式，按推荐程度排序：

1. 使用绝对导入（最推荐） #

先明确你的目录结构：

home/
├── file.py
└── common/
    └── utils.py

• 如果你运行代码时的工作目录是home的上级目录（或者已经把home所在路径加到Python的sys.path里），直接用绝对导入：
  在file.py里修改导入语句：

  from home.common.utils import hello
  

• 如果你的工作目录就是home（比如打开终端cd到home目录，然后运行python file.py），可以简化成：

  from common.utils import hello
  

  这时候Python会在sys.path包含的home目录下找到common目录，进而定位到utils模块。

2. 将common转为正式Python包（规范做法） #

在home/common目录下创建一个空的__init__.py文件，让Python把common识别为一个合法的包：

home/
├── file.py
└── common/
    ├── __init__.py
    └── utils.py

之后导入方式和上面的绝对导入一致就行。这是Python包结构的规范要求，推荐加上，尤其是当你的项目规模变大、需要拆分更多模块时，能避免很多奇怪的导入问题。

3. 临时手动添加路径（仅用于临时测试，不推荐长期用） #

如果你只是临时需要让代码跑起来，可以在file.py的开头手动把common目录加到sys.path里：

import sys
from pathlib import Path

# 获取当前文件所在目录下的common路径，添加到sys.path
sys.path.append(str(Path(__file__).parent / "common"))

from utils import hello

这种方法不推荐长期用，因为会破坏Python的模块化规范，而且路径处理容易因为项目结构变化出问题。

另外提醒一句：别直接用相对导入（比如from .common.utils import hello）运行file.py，因为当你用python file.py启动时，file.py会被当作__main__模块，相对导入在这种场景下会报错。如果一定要用相对导入，得把home当作包来运行，比如在home的上级目录执行python -m home.file。

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