Python与PyCharm运行子包模块的差异及命令行报错解决

这个问题本质是Python路径查找机制的差异：PyCharm会自动把你的项目根目录加入到sys.path（Python查找模块的路径列表）里，但直接用命令行运行单个脚本时，默认只会把脚本所在目录加入sys.path，导致找不到目标子包。下面是几个实用的解决办法：

方法1：从项目根目录以模块方式运行（最推荐） #

假设你的项目结构大概是这样的：

your_project_root/
├── pkg/
│   ├── __init__.py
│   ├── engine.py
│   └── ai.py
└── test_script.py

不要直接进入pkg目录运行engine.py，而是回到项目根目录，用模块调用的方式执行：

python -m pkg.engine

这样Python会自动把项目根目录作为模块搜索起点，就能正确识别pkg下的所有子模块了。

方法2：手动把项目根目录加入sys.path #

如果确实需要直接在engine.py所在目录运行它，可以在engine.py的最顶部添加以下代码（必须放在所有导入语句之前）：

import sys
import os

# 获取当前脚本所在目录的父目录（即项目根目录）
project_root = os.path.dirname(os.path.abspath(__file__))
# 若项目根目录不在路径列表中，就添加进去
if project_root not in sys.path:
    sys.path.insert(0, project_root)

这段代码会动态把项目根目录加入Python的路径搜索列表，确保导入ai.py时能被找到。

方法3：设置环境变量PYTHONPATH #

在命令行里，先把项目根目录配置到PYTHONPATH环境变量中，再运行脚本：

Windows命令行 #

set PYTHONPATH=your_project_root_full_path
python pkg/engine.py

Linux/macOS终端 #

export PYTHONPATH=your_project_root_full_path
python pkg/engine.py

这个方法不用修改代码，每次运行前设置一次即可；如果经常用到，可以把export命令加到你的shell配置文件（比如~/.bashrc或~/.zshrc）里，一劳永逸。

额外提醒 #

• 确保你的子包目录下都有__init__.py文件（哪怕是空文件），这样Python才会把它识别为可导入的包。
• 尽量避免在直接运行的脚本里用相对导入（比如from .ai import xxx），除非你用模块方式运行（方法1），否则相对导入在直接执行脚本时容易出问题。

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