解决 Python 模块导入失败：PyCharm 项目结构与路径管理解析

示意图，标记前：

标记后：

红色波浪线消失，导入成功！

🏷️ Python 模块导入机制

1. Python 在导入模块时，会在 sys.path 列表中搜索模块的路径。

2. 默认情况下，Python 会在以下路径中查找模块：

   • 当前脚本所在目录

   • PYTHONPATH 环境变量中设置的目录

   • 标准库目录（如 site-packages）

3. 问题：

   • 如果一个目录未被 Python 识别为“包”或“源目录”，那么 Python 在搜索 sys.path 时可能不会将这个目录包含在内，从而导致导入失败。

---

🚀 PyCharm 的“源根目录”（Source Root）机制

1. PyCharm 需要通过“源根目录”来识别哪些文件或文件夹属于 Python 项目结构。

2. 当你将 sources 标记为“源根目录”时，PyCharm 会自动将该目录添加到 sys.path 中。

3. 这样，Python 解释器在执行导入时，就可以在 sys.path 中找到这些模块。

---

🔎 为什么不标记就不行？

• 如果不标记为“源根目录”，sources 文件夹就会被视为普通文件夹，Python 解释器就不会在其中搜索模块，自然会导致导入失败。

• 标记为“源根目录”后，PyCharm 直接在后台帮你把这个目录添加到了 sys.path 中，所以模块就能被成功识别了。

---

🧠 总结：

✅ 将目录标记为“源根目录” = 将目录动态地加入 sys.path
✅ 加入到 sys.path = Python 解释器知道去哪里找模块
✅ PyCharm 负责管理路径，Python 负责导入模块

---